Merge remote-tracking branch 'origin/main' into 60-context-menu-action-sheet

Reviewed-on: #177

.pi/prompts/next-issue.md

@@ -0,0 +1,142 @@
+---
+description: Take on the next actionable backlog issue end to end, and stop
+---
+Take on exactly one issue from the YellowJacket backlog, end to end, and stop.
+
+Repo: yonlu/yellowjacket at https://git.ljones.me — API base
+https://git.ljones.me/api/v1/repos/yonlu/yellowjacket, auth with
+`-H "Authorization: token $GITEA_TOKEN"`. Default branch is `main`.
+
+## 1. Orient before you pick
+
+Read, in this order: `CLAUDE.md` (the architecture and the reasons behind
+it), `.pi/journal.md` (what happened last), `.planning/NOTES.md` (what was
+already considered and rejected), and `.planning/plans/active/`. Do not skip
+this because the issue looks small — most of this codebase's traps are
+written down in exactly one of those four places, and the ones that bite are
+the ones you didn't read.
+
+## 2. Pick the issue
+
+List open issues. Choose the single highest-value one that is *actionable
+right now*:
+
+- Order by `Priority/Critical` → `High` → `Medium` → `Low`. Within a tier,
+  prefer `Reviewed/Confirmed`, then `Kind/Bug` over `Kind/Enhancement` over
+  `Kind/Feature`.
+- Consult issue #73 (the roadmap) — if it sequences the candidates, that
+  ordering wins over the label ordering.
+- **Skip** anything labelled `Status/Blocked`, `Status/In Progress`,
+  `Status/Abandoned`, `Reviewed/Won't Fix`, `Reviewed/Duplicate`,
+  `Reviewed/Invalid`, or already carrying an open PR.
+- **Skip anything someone else is already on.** The label is not the only
+  claim, because a concurrent session may not have applied it — several pi
+  sessions run against this repo from separate worktrees under
+  `~/.paseo/worktrees/`. Run `git ls-remote --heads origin` and skip any
+  issue whose number or slug matches an existing branch (`60-…`,
+  `fix/<slug>`). A duplicated fix costs more than a skipped issue.
+- **Skip** anything that cannot be verified without hardware you do not
+  have: physical-device Android behaviour (audio output, on-device file
+  writes, real gesture input). A browser at 424px is not a phone — see the
+  Chrome 113 section of `CLAUDE.md`.
+- **Skip** intermittent-failure issues unless you can reproduce the failure
+  on demand within a few minutes. Chasing a 1-in-3 flake is an unbounded
+  task and does not belong in a scheduled run.
+- If nothing qualifies, say so, do nothing, and stop. An empty run is a
+  correct outcome.
+
+## 3. Claim it
+
+Add `Status/In Progress` to the issue and comment that you are picking it
+up. Then branch:
+
+```
+git fetch origin && git checkout -b <type>/<short-slug> origin/main
+```
+
+`<type>` matches the issue's `Kind` (`fix/`, `feat/`, `refactor/`, `test/`,
+`docs/`, `ci/`). Branch from `origin/main`, never by checking out `main`
+itself — this repo is worked from several git worktrees at once and `main`
+is checked out in one of them, so `git checkout main` fails outright.
+
+## 4. Do the work
+
+Fix the issue that was reported and nothing else. Match the surrounding
+code's style. Follow the constraints in `CLAUDE.md` rather than reasoning
+from first principles — where it explains why something is shaped the way it
+is, that shape is load-bearing and there is usually a test pinning it.
+
+**Anything else you discover becomes a new issue, not a bigger diff.** File
+it with the right `Area/`, `Kind/`, `Priority/` labels, describe the
+symptom before the theory, and link it from your PR. Scope creep is the
+failure mode this instruction exists to prevent.
+
+If the work turns out to be materially larger than the issue implied, stop:
+comment on the issue with what you found and what it would actually take,
+remove `Status/In Progress`, push nothing, and end the run.
+
+## 5. Verify — the right tier, not the cheapest one
+
+Run `make generate` if you touched `.sql` or `.templ`, and `make bindings`
+if you changed a bound Go signature. Then run what the change actually
+demands:
+
+- Go change → `make lint` and `make test` (both cover all three build
+  configurations).
+- Frontend component or store → `make ui-test`.
+- User-visible flow → `make e2e` against `make dev-headless`. **Check the
+  port first**: `ss -ltn | grep 34115`. If it is occupied, another worktree
+  is already running the app — do not start a second one and do not run
+  `make e2e`. Attaching to someone else's build produces a green result
+  about code that is not yours, which is worse than no result. Either
+  choose an issue that does not need this tier, or stop and say why.
+- Anything cosmetic or layout-related → look at a screenshot. Several bugs
+  in this repo's history were invisible to every assertion and obvious in an
+  image.
+
+A tier you skipped is a claim you did not check. If a tier fails for reasons
+unrelated to your change, say so explicitly rather than quietly moving on.
+
+## 6. Keep the documentation true
+
+If you changed structure, behaviour, or a constraint, update `CLAUDE.md` in
+the same commit. That file is this project's memory; a change that leaves it
+describing the old shape is worse than no change. Append a short entry to
+`.pi/journal.md` covering what you did, what you verified, and what you left
+open.
+
+## 7. Commit and open the PR
+
+Conventional Commits, imperative subject, ≤72 chars, scope optional. The
+body explains *why*. Push the branch — never push to `main`, never
+force-push.
+
+Open the PR:
+
+```
+curl -sS -X POST \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://git.ljones.me/api/v1/repos/yonlu/yellowjacket/pulls \
+  -d '{"head":"<branch>","base":"main","title":"<subject>","body":"<body>"}'
+```
+
+The body states: what the issue was, what you changed and why, **which
+verification tiers you ran and their results**, anything you deliberately
+did not do, and `Closes #<n>`.
+
+Then wait for CI (`ci.yml`, jobs `check` and `e2e`) and report the result on
+the PR. If it fails, read the log — `gitea_ci`'s `job_logs` 404s on this
+Gitea build, so use
+`GET /api/v1/repos/yonlu/yellowjacket/actions/runs/<run>/jobs` for per-step
+status and `GET /api/v1/repos/yonlu/yellowjacket/actions/jobs/<id>/logs` for
+the log — and fix it. Two consecutive failed CI runs on the same cause: stop,
+comment what you know on the PR, and leave it for a human.
+
+**Do not merge.** Comment on the issue linking the PR, leave
+`Status/In Progress` on, and end the run.
+
+## Finally
+
+Report in three lines: which issue you took, what state it is in
+(PR open / CI green / stopped and why), and any issues you filed.

.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:run:device       # debug build + install + launch on a phone
-wails3 task android:deploy-device    # production APK to a device
+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
+installs; `APP_ID` in `build/android/Taskfile.yml` was what every
-adb-driven task uninstalls, launches and filters. **Nothing enforces
+adb-driven task uninstalled, launched and filtered, and nothing
-that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
+enforced that they agree. They did not: the debug buildType carries
-`build/config.yml` does not work in beta.8 — `wails3 task` never reads
+`applicationIdSuffix ".dev"`, so every task that assembles a debug APK
-that file (verified with `--dry`), and even when set it feeds only the
+addressed the release id. This file flagged the hazard for five phases
-adb commands, never Gradle. Change both or the official `run`/`deploy`
+and it cashed out twice — once as a wrong `am start`, once as an
-tasks address a package that is not installed.
+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/plans/completed/018-supported-sizes-and-the-queue-model.md

@@ -3,7 +3,8 @@
 **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:** in flight
+**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
@@ -269,6 +270,38 @@ 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

CLAUDE.md

@@ -317,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
@@ -514,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
@@ -535,7 +646,11 @@ rather than renaming them.
   level rather than writing through to the volume, so it cannot
   accumulate and nothing persists or emits a level the user did not
   choose — and it only ever fires below API 26, where the framework
-  does not already duck the app itself.
+  does not already duck the app itself. On that platform "the user's
+  level" is a constant, since #64 pins it at maximum and refuses every
+  way to move it; the duck is the one thing that still may, and it
+  works unchanged because it was always an offset applied *to* that
+  level rather than a write of it.
 - `system` — OS-specific paths (XDG on Linux, `%LOCALAPPDATA%` on Windows).
 - `explore` — Catalog search and browse over `explore_index`. See below.
   Its **shelves** (`shelves.go`) are the page Explore shows before
@@ -945,13 +1060,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
@@ -1098,8 +1367,17 @@ against the real components:
   `wa-dropdown-item` sets its `role` in its *own* first update, so a
   `[role^="menuitem"]` query at `updateComplete` finds nothing — which
   reads exactly like a menu that opened and refused to take focus.
-- **`focus()` on a popup that has not positioned itself is a silent
+- **`focus()` on a surface that has not shown itself is a silent
-  no-op**, so the first focus is retried across a few frames.
+  no-op**, so the first focus is retried on a *time* budget rather
+  than a frame count — the thing being waited for is another
+  component's animation. And a retry is not enough on its own for the
+  sheet below: `wa-dialog` focuses `[autofocus]` or *itself* on the
+  frame after `showModal()`, and it cannot see the first menu item to
+  prefer it, because the panel is slotted through `menu-surface` and
+  the dialog's own `querySelector` stops at the `<slot>`. The first
+  attempt therefore *succeeds* and is then overwritten, which no
+  amount of waiting fixes — so the surface announces `menu-shown` when
+  it has settled and `MenuKeyboard.refocus()` re-asserts.
 - **Focus is only taken back if the menu had it.** A click elsewhere
   closes the menu too, and pulling focus to the row the user
   right-clicked a moment ago is worse than leaving it.
@@ -1107,6 +1385,69 @@ against the real components:
   moving focus without setting it leaves the highlight on whichever
   item the mouse last touched.
 
+**And a menu is drawn where it fits: a popup on a desktop, a bottom
+sheet on a phone** (#60). `components/menu-surface/` is that one
+decision. The host renders the panel it always rendered and slots it
+into whichever surface is up, so `ContextMenuController` still drives
+`.active` and `.anchor` as though it were talking to a `wa-popup`, and
+fourteen call sites changed one tag name each and nothing else.
+
+**It is a correctness fix, not a taste one, and the failure was
+measured on the device rather than inferred.** Chrome 113 has no
+Popover API, so `wa-popup` takes its own documented fallback and
+positions with `strategy: "fixed"`; `.main-panel` carries
+`contain: layout style paint`, and paint containment *clips* fixed
+descendants. On the reference device the main panel spans 0-318 of a
+439px viewport while the open menu spanned 191-401 — three of its seven
+items cut off, with no way to reach them. `showModal()` is Chrome 37
+and uses the real top layer, so a dialog is immune by construction.
+
+Six things about it are load-bearing.
+
+**"Dialogs are fine" needed checking, because every other dialog in
+this app is mounted in `index.html`** — outside `.main-panel` — so it
+was not evidence about one opened from inside a view. A probe dialog
+appended to `track-list`'s shadow root paints to y=439, over the mini
+player and the tab bar, with the contained ancestor still in place. A
+top-layer element's containing block is the viewport, contained
+ancestor or not.
+
+**The sheet has to un-do the UA stylesheet.** A native `<dialog>`
+carries `max-width: calc(100% - 6px - 2em)` and `margin: auto`, which
+drew a 354px panel floating in the middle of a 424px screen.
+`max-width: none` plus explicit margins is what makes it a sheet.
+
+**The row sizing lives in `contextMenuStyles`, not in the component.**
+The panel is the *host's* light DOM — it stays in the host's shadow
+root, so only the host's stylesheet can reach it. `menu-surface` puts
+`data-sheet` on the panel and that shared stylesheet does the rest,
+which is how fourteen menus went from 29px rows to 48px ones in one
+edit.
+
+**A dismissal has to travel back.** `wa-dialog` closes itself on
+Escape, which would leave the controller believing the menu is open —
+and the failure mode is not a stuck sheet but the *next* long-press
+doing nothing, which reads as the gesture breaking. `menu-dismiss` is
+that signal; the three surfaces that do not use `ContextMenuController`
+bind it themselves.
+
+**The playlist submenu is a sheet too, and it had to be.** It is a
+`placement="right-start"` flyout, and making the menu full-width moved
+its anchor — measured at x −182 to 0, entirely off-screen, so "Add to
+Playlist" led nowhere. It stacks as a second sheet over the first,
+which is also why `menu-shown` does not re-assert focus while the
+submenu is open.
+
+**And which call sites exist is swept, not remembered.** A thirteenth
+menu written as a bare `<wa-popup>` works perfectly in every tier here
+and is clipped on the device, so `menu-surface.test.ts` reads the
+source and fails on one outside a three-file allowlist —
+`menu-surface` itself, `job-indicator` (in `.top-bar`, which no
+ancestor contains — the contrast that proved the diagnosis on #62) and
+`now-playing`'s cover preview (a hover affordance, which a touch device
+never opens). **The sweep found two of the fourteen**; twelve were
+converted by hand.
+
 **And a menu opens from a finger, through the event it already has.**
 `utils/long-press.ts` is one document-capture listener installed once
 from `index.ts`: a touch that holds still for 500 ms dispatches a
@@ -1294,8 +1635,8 @@ still permits *programmatic* scrolling, so a probe that sets
 **Below 600px it reflows instead, and that is the phone.** The sideways
 scroll above was the concession available while the shell had one
 layout; plan 016 B2 gives it a second. Under 600px the grid drops its
-sidebar column, `<bottom-nav>` takes over as the primary navigation,
+sidebar column *and* (since #57) its top-bar row, `<bottom-nav>` takes
-the header's controls shrink or stand down, and the shell measures
+over as the primary navigation, and the shell measures
 exactly 320px in a 320px viewport — so `layout-overflow.spec.ts` now
 asserts *nothing needs scrolling to*, which is what WCAG 1.4.10 wanted
 all along. 600 rather than the sidebar's 900 because 900 is a laptop:
@@ -1336,6 +1677,238 @@ 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.
 
+**And below 600px there is no top bar at all** (#57). The row is gone
+from the phone's grid template — not the header hidden, the row deleted
+— which is 3.25em of a 439 CSS px viewport, the single biggest vertical
+win the reference device has to give. Each of its five children has
+somewhere else to be there: `nav-history` is the platform's own back
+gesture (already gone from 899 down), the job indicator is `<job-band>`
+(#62, which is why this was blocked on it), the search box is a
+`wa-dialog` opened from the view's own header, the library filter is
+Settings → Libraries (#148), and the wordmark stays exactly where it is.
+
+Three things about it are load-bearing. **The header is visually hidden
+rather than `display: none`**, because that `h1` is the document's
+top-level heading and several pages have no other one — `page-header`
+renders no `h1` when `heading` is `''`, and Settings has no
+`page-header` at all. Its four *controls* are `display: none` inside it,
+which is what keeps them out of the tab order: a visually-hidden
+container is still focusable, and tabbing into a search box nobody can
+see is worse than not having one. **The fit pass stands down**, from the
+bar's computed `position` rather than from a width — with the bar out of
+flow there is no content box to measure children against, and a pass
+that ran would collapse the wordmark every time and report success about
+a 1px box. And **`top-bar-fit.spec.ts` keeps 390 in its list and asserts
+the stronger property there**: "nothing hangs out of the bar" is
+trivially true of a bar with no row, and would have passed on a build
+that merely broke it, so what that width asks now is that the content
+starts where the row above it ends.
+
+**Above 600px 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` was the only control in the app that called
+`setSelectedLibrary` — so it trades this promise for the same promise.
+That is #148, and #57 fixed it by giving the selection a *second
+placement* rather than a second definition: the same component, in
+Settings → Libraries under a "Showing" label, at every width. A
+phone-only copy was the obvious cheaper answer and is the fault, not the
+fix — "where do I change which library I am browsing" having two answers
+by viewport is exactly what one control in two places avoids.
+Collapsing the search box to an icon is what #57 wanted and #57 was
+blocked behind #62, so building it here would have been building it
+without the thing that blocked 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. The bar's copy stands down below 600px, which
+is about *room*: five controls and a slider do not fit a 360px bar, and
+`now-playing-view` is where seeking and volume go on a phone.
+
+**Whether there is a volume to control at all is a different question,
+and it is asked of the player** (#64). On Android the hardware keys are
+the volume control and the framework mixes our stream against the
+device level, so `player`'s own level is pinned at maximum, `SetVolume`
+/ `ChangeVolume` / `MuteToggle` are refused, and `volume-control`
+renders `nothing` — in both of its mount points, at every width.
+`mediacontrols`' Android handler implementing no volume callback is the
+same fact one layer down.
+
+Five things about it are load-bearing.
+
+**It could not be a width, and that is not a preference.** Every other
+stand-down rule in this app is keyed on a viewport, because a width is
+what a browser can answer and what every tier can test. This one is a
+property of the build: keyed on width, an Android *tablet* at 600px or
+more draws the bottom bar's slider over a pinned level — a control that
+cannot act, on exactly the platform the rule exists for, which
+`library-status-indicator` already settled is worse than none. The
+same rule is wrong in the other direction below 600px, where a narrow
+desktop window has no hardware keys to fall back on.
+
+**The predicate is named after the capability, not the platform.**
+`SystemOwnsVolume` is what the frontend asks; `platformOwnsVolume` is
+the one build-tagged constant behind it, in two files that declare
+nothing else. That is `mediacontrols`' split with
+`androidpayload.go`'s reasoning: a tagged file is compiled by nothing
+`make lint` or `make test` runs, so everything decidable off a phone is
+decided against `Player.systemVolume`, a field a test sets either way.
+The frontend's absent branch is therefore testable in the component
+tier with a stubbed binding, and the constant itself is covered by a
+source sweep plus, once, a real arm64 device answering `true` — which
+is the only tier that compiles the `android` file at all.
+
+**Mute goes with it, because it is a level of zero by another name** —
+and because with no control rendered it is the one state on such a
+platform the user could not get out of.
+
+**Nothing persists a level nobody chose.** The maximum the player runs
+at is synthetic, so `restoreStateLocked` *remembers* the stored volume
+instead of applying it and `saveState` writes that same value back.
+The alternative — a second query that omits the column — buys nothing
+and is a second write path to keep in step.
+
+**And ducking is untouched, which is what makes the pin safe.**
+`SetDuck` applies its attenuation by re-applying the *user's* level
+through `setVolumeLocked`, so pinning that level to maximum leaves the
+offset arithmetic exactly as it was. It is the only thing that may move
+the output on such a platform, and it is the one volume-shaped path
+that is not refused.
+
+One thing to know before anyone offers to test it on a phone: **the
+duck is unreachable above API 25.** `WailsForegroundService` builds its
+`AudioFocusRequest` without `setWillPauseWhenDucked` from Oreo, so the
+framework attenuates us itself and never sends
+`AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK` — a device confirms it by logging
+`requestAudioFocus() … flags=0x0`. `minSdk` is 21, so this is live code
+rather than dead, on Android 5.0 to 7.1 and nowhere else.
+
+**And below 600px that bar carries three controls, not five** (#59).
+Shuffle, repeat and the queue button leave it; what is left is art,
+title/artist, favourite, and prev/play/next. `player-controls` is one
+component in two places and **the context is a property rather than a
+media query**, which is the exception to the rule two paragraphs down:
+on a phone the bar wants three controls and `now-playing-view` wants
+five, larger still, *at the same viewport* — so the host states the
+context and the viewport states the size band, and neither alone can
+express it. Sizes come from `--yj-control-*` custom properties set per
+context; play/pause alone goes above the 44px floor, because a row of
+identical squares says every action is equally likely and that is not
+true of play. Measured before #56: every one of them was **33×21px**,
+and the mini bar's favourite was **18×14**, the smallest control in the
+app.
+
+Four things about it are load-bearing.
+
+**The phone draws three buttons rather than hiding two**, from
+`matchMedia` — `job-band`'s pattern, and the rule that a decision about
+whether an element *exists* is not a stylesheet's to make. A
+`display: none` control is still in the shadow root and still something
+a positional query finds, so "the phone has three controls" would have
+been true of the pixels and false of the element.
+
+**Removing a control is only allowed because it is still reachable.**
+Plan 018's matrix promises no action is unreachable at any supported
+size, and all three are on `now-playing-view`, one tap away through the
+mini player's art. That promise is what `phone-transport.spec.ts`
+asserts — it walks the route — rather than counting buttons.
+
+**So the route to Now Playing must not depend on what is playing**, and
+it did. `now-playing` renders two branches and the no-track one had no
+`.expand` button on its placeholder, so with nothing loaded there was
+no way to the full-screen view — which, once the queue button left the
+bar, made the *queue* unreachable. The queue is persisted across
+restarts, so "tracks queued, nothing playing" is a state the app
+launches into.
+
+**The desktop bar is untouched and a spec says so with a literal.**
+Both issues are `Platform/Android`. The trap is that a `<button>` does
+not inherit its font from its parent — the UA stylesheet gives it one —
+so a generic `font-size: inherit` is not the no-op it reads as: it took
+every desktop button from 33×21 to 36×24, silently. The sizes are
+asserted as `'33x21'` rather than as a range, because the regression
+was three pixels.
+
 **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
@@ -1382,6 +1955,61 @@ 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.
 
+**And an overlaid queue is a place, which is the whole of #55.** The
+pixels were already right: measured at the reference device's 424×439,
+the overlaid panel is 424×318 — `.main-panel`'s rect exactly — so a
+`DETAIL_LOADERS` mount would draw the same rectangle in the same spot.
+What was missing was the navigation model, and the defect was one
+measurement: opening the queue on Artists and pressing back moved the
+page *underneath* to Albums and left the queue up. So opening an
+**overlay** queue dispatches `navigate {view: 'queue'}` and opening a
+**column** sets the attribute as it always did — `utils/open-queue.ts`
+is that one decision, and both routes end at the same `open` attribute
+on the same element.
+
+Five things about it are load-bearing.
+
+**The queue is a screen exactly while it is an overlay**, which is the
+rule above rather than a second one: a column is a thing the user
+docked, so back must not undock it and a navigation must not take it
+away, while an overlay is covering the content and has to answer the
+platform's gesture. That also inherits the *computed, not
+breakpointed* property for free — the panel is drag-resizable, so a
+viewport breakpoint would be wrong by up to 180px.
+
+**It is in neither `VIEW_TAGS` nor `DETAIL_LOADERS`**, because there is
+nothing to mount; the panel is already in the document. That is not
+tidiness. `.main-panel > *` is paint-contained under a `.main-panel`
+that is, and `contain: paint` clips the `position: fixed` a `wa-popup`
+falls back to on the reference device's Chrome 113 (#60) — so the
+detail-view mount asked for in #55's Direction would have broken
+`queue-panel`'s working context menu on the one device the issue is
+about. Measured: the panel's ancestry is `layout style` all the way to
+`body`; a view inside the main panel is `content` under `content`.
+**No tier here can see that consequence** — CI's Chromium and WebKit
+both have the Popover API — so `queue-as-a-screen.spec.ts` asserts the
+*mechanism*, that the panel is not under a paint-contained ancestor.
+
+**A navigation to `queue` deliberately writes neither
+`dataset.activeView` nor `searchStore.setCurrentView`**, because both
+describe what is *in* the main panel and the queue covers that panel
+without replacing it. It publishes itself through `activeViewStore`
+with `isPrimary: false`, so the tab it was opened from stays lit —
+the same rule a detail view gets.
+
+**The entry is unwound from the panel's `open` attribute**, in the
+mutation observer `index.ts` already ran for `aria-expanded`, rather
+than at each of the four ways out. Escape, the scrim, the close button
+and the toggle all take that route, and a fifth added later gets it
+free. Without it the entry is orphaned and the *next* back press is the
+one that closes the queue — the reported defect moved one press later,
+which looks exactly like a press that did nothing.
+
+**And the way out is 44px on a phone.** With the panel spanning the
+whole width the scrim has no uncovered pixels at all, so the close
+button is the only pointer route out of a full-screen surface; it was
+**25×21px**.
+
 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
@@ -1980,6 +2608,96 @@ 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.
+
+**The count is the last thing to yield, and only at 320px.** Four
+things compete for that row and three of them cannot go: the title
+yields first and is allowed to ellipsis away entirely, because the
+navigation also says which page you are on; the sort control and the
+actions are each the only place they are said, which is what the
+overflow menu exists for. That leaves the count, which is the one
+purely informational item there — an empty page says so in its empty
+state and a full one is being looked at. It became reachable rather
+than theoretical with #57, since below 600px this header also carries
+the phone's search button: measured on Playlists at 320px, title 0,
+count 50, sort 143, search 40, "More actions" 38, five 12px gaps and
+32px of gutters — 363 in 320, with the More button ending 27px past
+the edge. It is rendered and hidden with an attribute rather than
+returned as `nothing`, for the reason the action buttons are: every
+pass starts from all-visible and needs a node to un-hide, or the first
+320px window costs the count for the rest of the session.
+
+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
@@ -1996,6 +2714,54 @@ term belongs in that map**, detail views included —
 placeholder saying there was nothing to search here, because its
 sibling was in the map and it was not.
 
+**On a phone the box is a modal, and the map is what decides who gets
+one** (#57). There is no header to hold it below 600px, so
+`<search-trigger>` is a button in the row that already says which page
+you are on and `<search-dialog>` is where the box goes — and both ask
+`searchStore.isSearchableView()` rather than being told, which is the
+whole reason the trigger is an element and not a `PageAction`. Seven
+hosts each declaring a search action would be a second list of
+searchable views, and putting the decision inside `page-header` would
+be the phone mode for actions that component documents its refusal to
+grow.
+
+Four things about it are load-bearing.
+
+**It is a `wa-dialog`, and that is a mechanism rather than a taste.**
+#60 read out of the Web Awesome source that `wa-popup` renders
+`<div popover="manual">` and feature-detects the Popover API, falling
+back to `strategy: "fixed"` where there is none — which is Chrome 113,
+the reference device, since `popover` is Chrome 114. `position: fixed`
+escapes ancestor overflow but **not** `contain: paint`, which
+`.main-panel` carries, so a popup-shaped search panel opened from a
+view's header is structurally clipped on that device. `<dialog>` /
+`showModal()` is Chrome 37 and uses the real top layer. **No tier here
+can see the difference** — CI's Chromium and WebKit both have the
+Popover API, so the popup would be top-layered and correct and a spec
+asserting "not clipped" would pass on the broken build. The component
+tier asserts the *mechanism* instead: that there is a native `<dialog>`
+in the tree.
+
+**It carries the real `<search-bar>`**, not a second input, which is
+what keeps one debounce, one clear button and one view-scoped
+placeholder. `--yj-search-max-width` is the one thing the modal changes
+about it: 360px is a cap for a header, not for a control that has the
+whole of a 424px screen.
+
+**The results are the page, not a list in the modal.** The term is
+view-scoped and the view behind already filters on it and says
+"Showing tracks matching …", so Enter closes and hands the screen back.
+Rendering results in the dialog would be a second implementation of
+every view's filtering, and one that could not offer the row actions
+the view does.
+
+**Escape closes and keeps the term.** `search-bar`'s own input treats
+Escape as *clear the search*, which is right in a header where the box
+is on screen either way; in a modal it would mean dismissing the search
+surface silently discarded the search. The dialog takes the key in the
+capture phase on its own host, which is the only listener that runs
+before the input inside `search-bar`'s shadow root.
+
 **The window's minimum is measured, not aspirational.** `MinWidth`/
 `MinHeight` are 800×600 because that is where the shell was checked to
 still work: below ~780 the header subtitle wraps and pushes the title

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 {
+	spec, known := LookupView(string(c.DefaultPage))
-	case DefaultPageHome, DefaultPageTracks, DefaultPageAlbums, DefaultPageArtists,
+	if !known {
-		DefaultPageGenres, DefaultPagePlaylists, DefaultPageExplore, DefaultPageDownloads,
-		DefaultPageAutotag, DefaultPageJobs:
-		// Valid.
-	default:
 		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/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/player/player.go

@@ -71,6 +71,19 @@ type Player struct {
 	// not something the user chose.
 	duckAmount float64
 
+	// systemVolume is what SystemOwnsVolume answers: the platform's own
+	// control is the only one, so ours neither acts nor persists.  It is
+	// a field rather than the build constant read directly so that a
+	// test can exercise both sides on any machine.  See systemvolume.go.
+	systemVolume bool
+
+	// storedVolume and storedMuted hold the persisted level as it was
+	// found at restore, for a platform whose volume we do not own: the
+	// maximum we then run at is not a level the user chose, so saveState
+	// writes back what it read rather than overwriting it.
+	storedVolume UserVolume
+	storedMuted  bool
+
 	// trackLengthMs holds the authoritative track duration in
 	// milliseconds, sourced from the database (which uses the
 	// custom header parser).  The go-mp3 decoder's Len() can be
@@ -156,6 +169,8 @@ func NewPlayer(logger *slog.Logger, db *database.DB) *Player {
 		logger:       logger,
 		db:           db,
 		state:        Stopped,
+		systemVolume: platformOwnsVolume,
+		storedVolume: DefaultUserVol,
 		baseStreamer: generators.Silence(-1),
 		format: beep.Format{
 			SampleRate: speakerSampleRate,
@@ -875,6 +890,10 @@ func (p *Player) SetVolume(desiredVolume UserVolume) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
+	if p.systemVolume {
+		return
+	}
+
 	p.setVolumeLocked(desiredVolume)
 	p.emitVolumeChanged()
 	p.saveState()
@@ -923,6 +942,10 @@ func (p *Player) ChangeVolume(deltaVolume int) error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
+	if p.systemVolume {
+		return nil
+	}
+
 	p.setVolumeLocked(p.getUserVolume() + UserVolume(deltaVolume))
 	p.emitVolumeChanged()
 	p.saveState()
@@ -953,6 +976,14 @@ func (p *Player) MuteToggle() error {
 		return errNoAudioFileLoaded
 	}
 
+	// Mute is a level of zero by another name, so it goes with the rest
+	// of the volume where the system owns it -- and it would be the one
+	// state on such a platform the user could not get out of, since with
+	// no control rendered there is nothing left to un-mute with.
+	if p.systemVolume {
+		return nil
+	}
+
 	speaker.Lock()
 	p.volume.Silent = !p.volume.Silent
 	speaker.Unlock()
@@ -1403,7 +1434,15 @@ func (p *Player) saveState() {
 	volume := int64(DefaultUserVol)
 	muted := false
 
-	if p.volume != nil {
+	switch {
+	case p.systemVolume:
+		// The maximum this platform runs at is not a level anybody
+		// chose, so it is not one to remember.  Writing back what
+		// restore found keeps the row a description of the user's
+		// setting without needing a second query that omits the column.
+		volume = int64(p.storedVolume)
+		muted = p.storedMuted
+	case p.volume != nil:
 		volume = int64(p.getUserVolume())
 		muted = p.volume.Silent
 	}
@@ -1487,11 +1526,20 @@ func (p *Player) restoreStateLocked() {
 		}
 	}
 
-	vol := clampVolume(UserVolume(state.Volume))
+	if p.systemVolume {
-	p.setVolumeLocked(vol)
+		// Remembered, not applied: the device's keys are the volume
+		// control here, so the player runs wide open and hands the
+		// stored level back untouched at the next save.
+		p.storedVolume = clampVolume(UserVolume(state.Volume))
+		p.storedMuted = state.Muted
+		p.setVolumeLocked(MaxUserVol)
+	} else {
+		vol := clampVolume(UserVolume(state.Volume))
+		p.setVolumeLocked(vol)
 
-	if state.Muted {
+		if state.Muted {
-		p.volume.Silent = true
+			p.volume.Silent = true
+		}
 	}
 
 	// Restore last track if the file still exists.
@@ -1531,8 +1579,9 @@ func (p *Player) restoreStateLocked() {
 	}
 
 	p.logger.Info("Player state restored",
-		"volume", vol,
+		"volume", p.getUserVolume(),
-		"muted", state.Muted,
+		"muted", p.volume.Silent,
+		"systemVolume", p.systemVolume,
 		"trackPath", state.LastTrackPath,
 		"positionSeconds", state.LastPositionSeconds,
 	)

backend/player/systemvolume.go

@@ -0,0 +1,42 @@
+package player
+
+// Who owns the volume, and what follows when it is not us.
+//
+// On Android the hardware keys *are* the volume control and the
+// framework mixes our stream against the device level, so a second
+// control inside the app is a slider that moves something the user
+// already moved (#64).  Where that is true the player's own level sits
+// at maximum, nothing changes it, and nothing persists it.
+//
+// **The predicate is named after the capability, not the platform.**
+// The frontend asks "is there a volume for me to control", which is a
+// question about this build; asking "is this a phone" instead would
+// key the answer to a viewport, and an Android tablet at 600px or more
+// would then draw the bottom bar's slider over a level pinned at
+// maximum -- a control that cannot act, which is the thing
+// `library-status-indicator` already settled is worse than none.
+//
+// **Only `platformOwnsVolume` is behind a build tag**, in two files
+// that declare nothing else.  A tagged file is compiled by nothing
+// `make lint` or `make test` runs and is untestable off a phone, which
+// is the reasoning `mediacontrols/androidpayload.go` states for
+// keeping its contract out of one -- so everything decidable here is
+// decided against `Player.systemVolume`, a field a test sets either
+// way, and the tag decides only what that field starts as.
+//
+// The one thing this must not disturb is ducking.  `SetDuck` applies
+// its attenuation by re-applying the *user's* level through
+// `setVolumeLocked`, so pinning that level to maximum leaves the
+// offset arithmetic exactly as it was: an OS asking us to get out of
+// the way of a navigation prompt is not the user setting a volume, and
+// it is the only thing that may move the output on such a platform.
+
+// SystemOwnsVolume reports whether the platform's own control is the
+// only volume control there is, so this app neither offers one nor
+// remembers a level.
+//
+// It is bound: the frontend renders no `<volume-control>` when it is
+// true, at any width.
+func (p *Player) SystemOwnsVolume() bool {
+	return p.systemVolume
+}

backend/player/systemvolume_android.go

@@ -0,0 +1,11 @@
+//go:build android
+
+package player
+
+// platformOwnsVolume is true on Android: volume is the device's, set
+// with the hardware keys, and `mediacontrols`' Android handler
+// implements no volume callback for the same reason.
+//
+// See systemvolume.go for why this constant is the whole of what a
+// build tag decides here.
+const platformOwnsVolume = true

backend/player/systemvolume_other.go

@@ -0,0 +1,10 @@
+//go:build !android
+
+package player
+
+// platformOwnsVolume is false everywhere but Android: a desktop mixer
+// is per-application, so our level is the one the user reaches for.
+//
+// See systemvolume.go for why this constant is the whole of what a
+// build tag decides here.
+const platformOwnsVolume = false

backend/player/systemvolume_test.go

@@ -0,0 +1,215 @@
+package player
+
+import (
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/gopxl/beep/v2/effects"
+
+	"yellowjacket/backend/database"
+)
+
+// pinnedPlayer is a player on a platform whose volume belongs to the
+// device.  The field is set rather than the build constant read,
+// because the constant is true on exactly one platform and no tier
+// here runs on it -- see systemvolume.go.
+func pinnedPlayer(t *testing.T, db *database.DB) *Player {
+	t.Helper()
+
+	p := NewPlayer(slog.Default(), db)
+	p.systemVolume = true
+	p.volume = &effects.Volume{Base: 2}
+	p.setVolumeLocked(MaxUserVol)
+
+	return p
+}
+
+// TestSystemVolumeRefusesEveryWayToChangeTheLevel is the first half of
+// #64: where the device owns the volume, ours sits at maximum and none
+// of the three routes to a level moves it.  Mute is in that list
+// because it is a level of zero by another name, and because with no
+// control rendered it is the one state on such a platform there would
+// be nothing to get out of.
+func TestSystemVolumeRefusesEveryWayToChangeTheLevel(t *testing.T) {
+	t.Parallel()
+
+	p := pinnedPlayer(t, nil)
+
+	if !p.SystemOwnsVolume() {
+		t.Fatal("SystemOwnsVolume() = false on a pinned player")
+	}
+
+	if got := p.getUserVolume(); got != MaxUserVol {
+		t.Errorf("starting volume = %d, want %d", got, MaxUserVol)
+	}
+
+	p.SetVolume(20)
+
+	if got := p.getUserVolume(); got != MaxUserVol {
+		t.Errorf("volume after SetVolume(20) = %d, want %d", got, MaxUserVol)
+	}
+
+	if err := p.ChangeVolume(-30); err != nil {
+		t.Fatalf("ChangeVolume: %v", err)
+	}
+
+	if got := p.getUserVolume(); got != MaxUserVol {
+		t.Errorf("volume after ChangeVolume(-30) = %d, want %d", got, MaxUserVol)
+	}
+
+	if err := p.MuteToggle(); err != nil {
+		t.Fatalf("MuteToggle: %v", err)
+	}
+
+	if p.volume.Silent {
+		t.Error("MuteToggle silenced a player whose volume the system owns")
+	}
+}
+
+// TestAnUnpinnedPlayerStillChangesItsVolume is the other side of the
+// same switch.  Without it the test above passes on a player that
+// refuses everything, which is what a mis-wired field would produce.
+func TestAnUnpinnedPlayerStillChangesItsVolume(t *testing.T) {
+	t.Parallel()
+
+	p := NewPlayer(slog.Default(), nil)
+	p.volume = &effects.Volume{Base: 2}
+	p.setVolumeLocked(MaxUserVol)
+
+	if p.SystemOwnsVolume() {
+		t.Fatal("SystemOwnsVolume() = true off Android")
+	}
+
+	p.SetVolume(20)
+
+	if got := p.getUserVolume(); got != 20 {
+		t.Errorf("volume after SetVolume(20) = %d, want 20", got)
+	}
+
+	if err := p.MuteToggle(); err != nil {
+		t.Fatalf("MuteToggle: %v", err)
+	}
+
+	if !p.volume.Silent {
+		t.Error("MuteToggle did not silence an ordinary player")
+	}
+}
+
+// TestSystemVolumeStillDucks is the issue's second Finding, made a
+// test: pinning the user's level must leave the OS's attenuation
+// working, because a duck is not a volume the user chose and is the
+// only thing that may move the output on such a platform.
+func TestSystemVolumeStillDucks(t *testing.T) {
+	t.Parallel()
+
+	p := pinnedPlayer(t, nil)
+	open := p.volume.Volume
+
+	p.SetDuck(true)
+
+	if p.volume.Volume >= open {
+		t.Errorf(
+			"ducked output = %v, want less than %v", p.volume.Volume, open,
+		)
+	}
+
+	if got := p.getUserVolume(); got != MaxUserVol {
+		t.Errorf("user volume while ducked = %d, want %d", got, MaxUserVol)
+	}
+
+	// A refused SetVolume must not disturb the offset either: it
+	// returns before setVolumeLocked, which is what re-applies it.
+	ducked := p.volume.Volume
+
+	p.SetVolume(10)
+
+	if p.volume.Volume != ducked {
+		t.Errorf(
+			"output after a refused SetVolume = %v, want %v",
+			p.volume.Volume, ducked,
+		)
+	}
+
+	p.SetDuck(false)
+
+	if p.volume.Volume != open {
+		t.Errorf("output after unduck = %v, want %v", p.volume.Volume, open)
+	}
+}
+
+// TestSystemVolumeWritesBackTheLevelItFound is the rest of the
+// Direction: "make sure nothing writes a persisted volume from that
+// platform".  The maximum the player runs at is synthetic, so saving
+// must not record it over whatever the row already said.
+func TestSystemVolumeWritesBackTheLevelItFound(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+
+	// A level set by some earlier, unpinned session.
+	writer := NewPlayer(slog.Default(), db)
+	writer.volume = &effects.Volume{Base: 2}
+	writer.setVolumeLocked(30)
+	writer.SaveState()
+
+	p := pinnedPlayer(t, db)
+	p.RestoreState()
+
+	if got := p.getUserVolume(); got != MaxUserVol {
+		t.Errorf("restored volume = %d, want %d (the level is pinned)", got, MaxUserVol)
+	}
+
+	if p.volume.Silent {
+		t.Error("restore muted a player whose volume the system owns")
+	}
+
+	p.SaveState()
+
+	state, err := db.Queries.GetPlayerState(db.Ctx)
+	if err != nil {
+		t.Fatalf("GetPlayerState: %v", err)
+	}
+
+	if state.Volume != 30 {
+		t.Errorf("persisted volume = %d, want 30 (untouched)", state.Volume)
+	}
+}
+
+// TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform sweeps the
+// source, because the pair of tagged files is the one thing here no
+// tier compiles both halves of: `make lint` and `make test` build the
+// `!android` side only, so a deleted or edited android file fails
+// nothing until somebody has a phone in their hand.
+func TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform(t *testing.T) {
+	t.Parallel()
+
+	want := map[string]string{
+		"systemvolume_other.go":   "const platformOwnsVolume = false",
+		"systemvolume_android.go": "const platformOwnsVolume = true",
+	}
+
+	tags := map[string]string{
+		"systemvolume_other.go":   "//go:build !android",
+		"systemvolume_android.go": "//go:build android",
+	}
+
+	for name, decl := range want {
+		src, err := os.ReadFile(filepath.Join(".", name))
+		if err != nil {
+			t.Errorf("%s: %v", name, err)
+
+			continue
+		}
+
+		if !strings.Contains(string(src), decl) {
+			t.Errorf("%s does not declare %q", name, decl)
+		}
+
+		if !strings.Contains(string(src), tags[name]) {
+			t.Errorf("%s does not carry %q", name, tags[name])
+		}
+	}
+}

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",

build/android/Taskfile.yml

@@ -4,18 +4,28 @@ includes:
   common: ../Taskfile.yml
 
 vars:
-  # The *installed* package name, which every adb-driven task below uses
+  # APP_ID is an *assertion*, not a setting, and it has no default.
-  # to uninstall, launch and filter. It must agree with `applicationId`
-  # in app/build.gradle, and nothing enforces that.
   #
-  # ANDROID.md says to set this in build/config.yml. That does not work
+  # It used to be the id every adb-driven task below uninstalled,
-  # in beta.8, checked both ways: `wails3 task` builds its var set from
+  # launched and filtered, defaulting to "app.yellowjacket". It could
-  # CLI KEY=VALUE arguments and the Taskfile tree only -- nothing reads
+  # never have been a setting: `wails3 task` builds its var set from CLI
-  # config.yml -- and even when set it feeds only these adb commands,
+  # KEY=VALUE arguments and the Taskfile tree only -- nothing reads
-  # never Gradle. So the identity is declared twice, here and in
+  # build/config.yml, contrary to ANDROID.md, checked with --dry -- and
-  # build.gradle, and a change to one alone means the official run and
+  # even when set it fed only the adb commands, never Gradle. So the
-  # deploy tasks address a package that is not installed.
+  # identity was declared twice, here and as `applicationId` in
-  APP_ID: '{{.APP_ID | default "app.yellowjacket"}}'
+  # 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'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
 
   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'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
 
   device:list:
     summary: Lists connected Android devices and emulators (serials)
@@ -400,25 +406,7 @@ tasks:
           ARCH: arm64
     cmds:
       - task: assemble:apk
-      - |
+      - './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}}'
-        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
     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:
-      - |
+      - './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}}'
-        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
     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) {

e2e/specs/album-dropdown.spec.ts

@@ -110,27 +110,30 @@ test.describe('the album dropdown', () => {
     await app.setViewportSize({ width: 900, height: 600 });
 
     try {
-      // Wait for the range the assertion below actually needs, not for
+      // The container has to be a scroller at all, which is the thing
-      // "scrollable at all" (#133). The guard used to be
+      // the defect behind this spec broke and is a property rather
-      // `scrollHeight > clientHeight + 40` while the next line asks to
+      // than a moment.
-      // reach 80, so any range in 41-79 satisfied it and could not
-      // satisfy the assertion — and the grid passes through exactly
-      // that while it settles, because it recomputes its columns after
-      // the resize rather than during it. The settled range here is
-      // 330, so this waits rather than weakening anything.
       await expect
         .poll(() => scrollRange(app))
-        .toMatchObject({ room: true, overflowY: 'auto' });
+        .toMatchObject({ overflowY: 'auto' });
 
-      await app.evaluate((target) => {
+      // **Scrolling it and reading it back are one round trip** (#151).
-        const sc = document
+      //
-          .querySelector('cover-grid')
+      // #133 made the guard ask for the range this needs rather than
-          ?.shadowRoot?.querySelector('.grid-scroll-container');
+      // for "scrollable at all", which was necessary and is not
-
+      // sufficient: a guard and the write it guards are separate
-        if (sc) sc.scrollTop = target;
+      // `evaluate` calls, so the grid can satisfy the range and settle
-      }, SCROLL_TARGET);
+      // out of it before the write lands. It still does — observed as
-
+      // `Expected 80, Received 10` in the second of three consecutive
-      expect(await scrollTop(app)).toBe(SCROLL_TARGET);
+      // 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
@@ -261,7 +264,7 @@ 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((target) => {
     const sc = document
@@ -269,22 +272,37 @@ async function scrollRange(app: Page) {
       ?.shadowRoot?.querySelector('.grid-scroll-container');
 
     return {
-      // `room` is the precondition of the assertion that follows it:
+      // Reported for the failure message rather than waited on: `room`
-      // enough range to actually reach the target. A threshold below
+      // was the guard #133 strengthened, and #151 is that a guard in
-      // what the caller depends on is not a guard.
+      // 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(
+ * Scroll the grid and report where it actually landed, in one call.
-    () =>
+ *
-      document
+ * The whole point is that the set and the read share a moment: a
-        .querySelector('cover-grid')
+ * `scrollTop` write is clamped to the range *at the instant it lands*,
-        ?.shadowRoot?.querySelector('.grid-scroll-container')?.scrollTop ?? -1,
+ * 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
+    // No disclosure to open first, and no state to put back afterwards:
-    // queue panel renders no list — so this has to open it first.
+    // #42 made the slider inline, so it is simply there. The assertion
-    await app.getByRole('button', { name: /volume/i }).click();
+    // 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

@@ -33,6 +33,14 @@ const VIEWPORTS = [
   // 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 },
 ];
 
 /**
@@ -93,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
+    // Settings is the one that was unreachable: it is last in the nav,
-    // last in the nav, and the pane used to clip rather than scroll.
+    // and the pane used to clip rather than scroll. (Jobs was the other
-    for (const view of ['jobs', 'settings'] as const) {
+    // 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();
@@ -123,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>(
+    // The scroll and the measurement share one `evaluate` — #151's
-        '[data-testid="nav-settings"]',
+    // 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 item = settings.getBoundingClientRect();
-      const pane = el.getBoundingClientRect();
+          const pane = el.getBoundingClientRect();
 
-      return item.bottom <= Math.ceil(pane.bottom) && item.top >= Math.floor(pane.top);
+          return (
-    });
+            item.bottom <= Math.ceil(pane.bottom) &&
-
+            item.top >= Math.floor(pane.top)
-    expect(reachable).toBe(true);
+          );
+        }),
+      )
+      .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
@@ -245,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(() => {
+      // Polled, for the reason the track-row test above is: since #143
-        const de = document.documentElement;
+      // 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;
+            return de.scrollWidth - de.clientWidth;
-      });
+          }),
-
+        )
-      // The other half: at every size this app promises, the fix costs
+        .toBe(0);
-      // nothing. A scrollbar that is always there is a worse answer
-      // than the clipping it replaced.
-      expect(excess).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-search.spec.ts

@@ -0,0 +1,322 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * #57. Below 600px the top bar is not in the layout, and search is a
+ * button that opens a modal on the pages where searching means
+ * anything.
+ *
+ * **This is the tier that can answer it, with one honest exception.**
+ * The shell's breakpoints are media queries, which the component tier
+ * cannot set — so whether the bar is a grid row, and whether a header
+ * grows a search button, is a question for a real viewport. What this
+ * tier *cannot* answer is the reason the surface is a `wa-dialog`:
+ * #60 read out of the Web Awesome source that `wa-popup` falls back to
+ * `position: fixed` where there is no Popover API (Chrome 113, the
+ * reference device) and that `.main-panel`'s `contain: paint` clips a
+ * fixed descendant. Chromium and WebKit here both have the Popover API,
+ * so a popup is top-layered and correct, and **an assertion that the
+ * modal is not clipped would pass on the broken build.** The mechanism
+ * is asserted in `frontend/test/components/search-dialog.test.ts`
+ * instead, where "is there a native <dialog>" is a question a browser
+ * can answer without lying.
+ *
+ * **And it is measured per element.** `layout-overflow.spec.ts` asks
+ * whether the *shell* needs sideways scrolling and was green throughout
+ * the defect it is named for; the win this issue is for is vertical and
+ * belongs to one element, so it is that element's box that is read.
+ */
+type Page = import('@playwright/test').Page;
+
+/** The reference device's own viewport, and a common small phone. */
+const DEVICE = { width: 424, height: 439 };
+const PHONE = { width: 390, height: 780 };
+
+/**
+ * Where the top bar is, and how much of the screen it costs.
+ *
+ * `contentTop` is measured against the *jobs band* rather than against
+ * the window, because that band is a real grid row whenever work is in
+ * flight (#62) and the app under these specs is long-lived — a job
+ * staged by another file is still in the store. Measuring against zero
+ * makes this assertion say "and no background job is running", which is
+ * not what it is for and is not something it can arrange.
+ */
+const barBox = (page: Page) =>
+  page.evaluate(() => {
+    const bar = document.querySelector<HTMLElement>('header.top-bar')!;
+    const main = document.querySelector<HTMLElement>('.main-panel')!;
+    const band = document.querySelector<HTMLElement>('job-band');
+    const cs = getComputedStyle(bar);
+
+    return {
+      position: cs.position,
+      height: Math.round(bar.getBoundingClientRect().height),
+      /** Where the content starts, and where the row above it ends. */
+      contentTop: Math.round(main.getBoundingClientRect().top),
+      aboveBottom: Math.round(band?.getBoundingClientRect().bottom ?? 0),
+    };
+  });
+
+test.describe('the phone has no top bar', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  /**
+   * The vertical win, measured rather than asserted by the absence of
+   * an element: `display: none` on the header would satisfy "the bar is
+   * hidden" while leaving a 3.25em grid row exactly where it was.
+   */
+  test('gives the row back to the content', async ({ app }) => {
+    const box = await barBox(app);
+
+    // Out of flow, so it takes no row — and 1px rather than 0, because
+    // it still carries the document's h1.
+    expect(box.position).toBe('absolute');
+    expect(box.height).toBeLessThanOrEqual(1);
+
+    // The content starts where the row above it ends, and there is no
+    // row above it but the jobs band. On `main` at the time of writing
+    // the content started 52px down from that point.
+    expect(box.contentTop).toBe(box.aboveBottom);
+  });
+
+  /**
+   * The wordmark yields its width and not its existence, which is the
+   * rule `top-bar-fit.ts` already lives by one band up: with the bar
+   * gone, `display: none` would take this document from one top-level
+   * heading to none on every page whose own header has no h1 —
+   * Settings has no `page-header` at all.
+   */
+  test('still has a top-level heading', async ({ app }) => {
+    await expect(
+      app.getByRole('heading', { name: 'YellowJacket', level: 1 }),
+    ).toHaveCount(1);
+  });
+
+  /**
+   * And its four controls are gone from the tab order, not merely from
+   * sight. A visually-hidden container is still focusable, and tabbing
+   * into a search box nobody can see is worse than not having one.
+   */
+  test('leaves nothing in the bar to tab into', async ({ app }) => {
+    for (const tag of [
+      'nav-history',
+      'library-filter',
+      'search-bar',
+      'job-indicator',
+    ]) {
+      await expect(app.locator(`header.top-bar ${tag}`)).toBeHidden();
+    }
+
+    const focusable = await app.evaluate(
+      () =>
+        document
+          .querySelector('header.top-bar')!
+          .querySelectorAll('input, select, button, a[href]').length,
+    );
+
+    // Nothing in the bar is *rendered*, so nothing in it can be
+    // focused; the controls are display:none, which takes their own
+    // shadow content with them.
+    expect(focusable).toBe(0);
+  });
+});
+
+test.describe('search on a phone', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(PHONE);
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  test('is a button in the view that can be searched', async ({ app }) => {
+    await app.getByTestId('tab-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+
+    // Scoped to the view: every cached primary view holds a
+    // `page-header`, and an unscoped testid is `bottom-nav`'s
+    // "resolved to 2 elements" trap again.
+    const trigger = app.locator('track-list page-header search-trigger button');
+
+    await expect(trigger).toBeVisible();
+    await expect(trigger).toHaveAttribute('aria-label', 'Search tracks');
+  });
+
+  /**
+   * The whole journey, which is the thing the issue asks for: a button,
+   * a modal, and the results on the page behind it saying what they are
+   * showing.
+   */
+  test('opens a modal, filters the page, and says so', async ({ app }) => {
+    await app.getByTestId('tab-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+
+    await app.locator('track-list page-header search-trigger button').click();
+
+    const dialog = app.getByTestId('search-dialog');
+
+    // Attached, not visible: `wa-dialog`'s host is `display: contents`,
+    // so the element carrying the testid always reports hidden — what
+    // is visible is the native `<dialog>` inside it. That awkwardness
+    // is written down in CLAUDE.md and is why the assertion that this
+    // is really up is the role query below.
+    await expect(dialog).toBeAttached();
+
+    // Named, which `getByRole` can answer and the a11y snapshot cannot
+    // — the snapshot never prints a dialog's name, named or not. This
+    // is also the assertion that the dialog is genuinely showing.
+    await expect(
+      app.getByRole('dialog', { name: 'Search tracks' }),
+    ).toBeVisible();
+
+    // Scoped: the header's own box is still in the document, hidden.
+    // This is the one moment there are two `search-input`s.
+    await dialog.getByTestId('search-input').fill('aurora');
+
+    // Enter hands the screen back, because the results are the page.
+    await app.keyboard.press('Enter');
+    await expect(dialog).not.toBeAttached();
+
+    // Polled: the box debounces by 150ms, so reading the page once
+    // straight after closing the dialog can capture the state before
+    // the term ever reached the store.
+    await expect
+      .poll(() =>
+        app.evaluate(
+          () =>
+            document
+              .querySelector('[data-testid="main-content"] track-list')
+              ?.shadowRoot?.querySelector('page-header')
+              ?.shadowRoot?.querySelector('[data-testid="page-search-scope"]')
+              ?.textContent?.trim() ?? '',
+        ),
+      )
+      .toMatch(/matching.*aurora/);
+
+    // And the button says the search is on, in its name rather than
+    // only in its colour.
+    await expect(
+      app.locator('track-list page-header search-trigger button'),
+    ).toHaveAttribute('aria-label', /aurora/);
+
+    // Leave the app as the next spec expects to find it.
+    await app.locator('track-list page-header search-trigger button').click();
+    await app.getByTestId('search-dialog').getByTestId('search-input').fill('');
+    await app.keyboard.press('Escape');
+  });
+
+  /**
+   * Two of the seven searchable views have no `page-header` — they are
+   * detail views that filter on the term and say so in their own
+   * headers. A trigger placed only in `page-header` would leave them
+   * with a search they can show and no way to set it, which is #24's
+   * sentence broken in the band it was written for.
+   */
+  test('reaches the playlist detail view too', async ({ app }) => {
+    await app.getByTestId('tab-playlists').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'playlists',
+    );
+
+    // `.playlist-item`, which is what the list renders. Asserted to
+    // exist rather than skipped on: the seed has a playlist, and a
+    // spec that quietly skips when its selector stops matching is a
+    // spec that reports success for a renamed class.
+    const first = app.locator('playlist-view .playlist-item').first();
+
+    await expect(first).toBeVisible();
+    await first.dblclick();
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'playlist-details',
+    );
+
+    await expect(
+      app.locator('playlist-details search-trigger button'),
+    ).toBeVisible();
+  });
+
+  /**
+   * A button that cannot do anything is worse than none — the rule
+   * `library-status-indicator` was rewritten on. Home has nothing of
+   * its own to search and is not in the store's map.
+   */
+  test('offers no button where there is nothing to search', async ({ app }) => {
+    await app.getByTestId('tab-home').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'home',
+    );
+
+    await expect(
+      app.locator('home-view page-header search-trigger button'),
+    ).toHaveCount(0);
+  });
+
+  test('offers no button on a desktop, where the header has a box', async ({
+    app,
+  }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+    await app.getByTestId('nav-tracks').click();
+
+    await expect(
+      app.locator('track-list page-header search-trigger button'),
+    ).toHaveCount(0);
+    await expect(app.locator('header.top-bar search-bar')).toBeVisible();
+  });
+});
+
+/**
+ * #148, which #57 inherits: `library-filter` is the only control in the
+ * app that calls `setSelectedLibrary`, and the bar it lived in is gone
+ * on a phone. #143 refused to hide it as a fit step for exactly this
+ * reason, so dropping it here would have been the same trade.
+ */
+test.describe('the library filter has a home that is not the bar', () => {
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  test('is in Settings, and is reachable from a phone', async ({ app }) => {
+    await app.setViewportSize(PHONE);
+
+    await app.getByTestId('tab-more').click();
+    await app.getByTestId('nav-drawer').getByTestId('nav-settings').click();
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'settings',
+    );
+
+    const filter = app.getByTestId('settings-library-filter');
+
+    await expect(filter).toBeVisible();
+    await expect(filter.locator('select')).toBeVisible();
+  });
+
+  test('and it is the same control at every width', async ({ app }) => {
+    // Not a phone-only copy: "where do I change which library I am
+    // browsing" having two answers by viewport is the fault, not the
+    // fix.
+    await app.setViewportSize({ width: 1440, height: 900 });
+    await app.getByTestId('nav-settings').click();
+
+    await expect(app.getByTestId('settings-library-filter')).toBeVisible();
+    await expect(app.locator('header.top-bar library-filter')).toBeVisible();
+  });
+});

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).
@@ -130,6 +130,25 @@ test.describe('the shell on a phone', () => {
     // are here, and they are the *same* components -- this view
     // composes the transport rather than reimplementing it.
     await expect(app.locator('now-playing-view seek-bar')).toBeVisible();
+
+    // Volume is here **because the player says there is one** (#64),
+    // not because this is a phone. This tier is the platform that owns
+    // its own volume, so what it can assert is that the control's
+    // presence follows that answer -- an inverted polarity in
+    // `volume-style-store` fails here and in `bottom-bar.spec.ts`, and
+    // the *absent* branch is checked in the component tier, where the
+    // binding can be stubbed. Nothing here can reach the Android side.
+    const systemOwns = await app.evaluate(
+      async () =>
+        (await window.__yjEvents.call(
+          'player.Player.SystemOwnsVolume',
+          [],
+          5_000,
+        )) as boolean,
+    );
+
+    expect(systemOwns, 'this platform should own its own volume').toBe(false);
+
     await expect(app.locator('now-playing-view volume-control')).toBeVisible();
 
     // Back goes where the user came from, through the nav stack.
@@ -138,6 +157,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 +245,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
+    // is not a thumb target -- both belong to the full-screen
-    // full-screen now-playing view.
+    // now-playing view.
-    await expect(app.locator('audio-player volume-control')).toBeHidden();
+    //
+    // `.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/phone-transport.spec.ts

@@ -0,0 +1,315 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * The phone's transport (#59, #56).
+ *
+ * #56 reports that "the playback controls are the most important thing
+ * in the mobile app and they are tiny". Measured at the reference
+ * device's 424x439 before this, every one of them was **33x21px**, and
+ * the favourite beside them — which #59 keeps on the bar — was
+ * **18x14px**, the smallest control in the app.
+ *
+ * #59 is what makes the sizes affordable: five controls plus a queue
+ * button at 44px does not fit 424 CSS px, so the bar carries three and
+ * the rest are on the full-screen view.
+ *
+ * **The assertion that matters is not the pixel count.** Plan 018's
+ * matrix promises that *no action is ever unreachable at any supported
+ * size*, and #59 removes three controls from the phone's bar — so the
+ * first thing this file checks is that all three are still reachable,
+ * by walking the route a user would. A spec that only measured the
+ * survivors would be green on a build that had made shuffle
+ * unreachable, which is the failure mode this pair of issues is one
+ * mistake away from.
+ */
+type Page = import('@playwright/test').Page;
+
+/** The reference device's real viewport. */
+const DEVICE = { width: 424, height: 439 };
+const PHONE = { width: 390, height: 780 };
+const DESKTOP = { width: 1280, height: 800 };
+
+/**
+ * The touch-target floor. 44px is what #56's Findings name and what
+ * #55's queue header was sized to, so the app has one number.
+ */
+const TARGET = 44;
+
+/** The play button is named for its action, not its identity. */
+const PLAY_PAUSE = /^(Play|Pause)$/;
+
+const barControls = (page: Page) =>
+  page.locator('audio-player player-controls');
+
+/**
+ * `name` may be a regex, and for play/pause it must be: that button is
+ * named for the *action*, so it is "Pause" while a track runs and
+ * "Play" when it stops. An exact 'Play' made these tests wait out a
+ * fixture track (11.1s each, passing by luck) and would have failed
+ * outright against `LONG_TRACK`. A test about a control's size does not
+ * care what the transport is doing.
+ */
+async function sizeOf(
+  page: Page,
+  name: string | RegExp,
+): Promise<[number, number]> {
+  const box = await page
+    .getByRole('button', { name, exact: typeof name === 'string' })
+    .boundingBox();
+
+  expect(box, `no button named ${name}`).not.toBeNull();
+
+  return [box!.width, box!.height];
+}
+
+/** Put something in the queue, so the transport has a track to act on. */
+async function stageATrack(page: Page): Promise<void> {
+  await page.evaluate(async () => {
+    const tracks = (await window.__yjEvents.call(
+      'library.Library.GetTracks',
+      [0],
+      10_000,
+    )) as { FilePath: string }[];
+
+    await window.__yjEvents.call(
+      'queue.Queue.SetQueue',
+      [tracks.slice(0, 4).map((t) => t.FilePath), 0, false, { type: '', id: 0, label: '' }],
+      10_000,
+    );
+  });
+}
+
+test.describe('the phone bar carries three controls', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await stageATrack(app);
+  });
+
+  test('drops shuffle, repeat and the queue from the bar', async ({ app }) => {
+    const bar = barControls(app);
+
+    await expect(bar.getByRole('button', { name: 'Previous track' })).toBeVisible();
+    await expect(bar.getByRole('button', { name: 'Next track' })).toBeVisible();
+
+    // Not in the bar's own subtree. Asserted against the bar rather
+    // than the page, because the whole point is that they moved rather
+    // than went away -- a page-wide `not.toBeVisible()` would fail the
+    // moment Now Playing is open and would be asserting the wrong
+    // thing besides.
+    await expect(bar.getByRole('button', { name: 'Shuffle' })).toHaveCount(0);
+    await expect(bar.getByRole('button', { name: /^Repeat/ })).toHaveCount(0);
+    await expect(app.locator('#queue-button')).toBeHidden();
+  });
+
+  /**
+   * The promise, walked. Every control #59 takes off the bar is
+   * reachable from the mini player's art in one tap.
+   */
+  test('leaves every removed control reachable from Now Playing', async ({
+    app,
+  }) => {
+    await app.getByTestId('open-now-playing').click();
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'now-playing',
+    );
+
+    await expect(app.getByRole('button', { name: 'Shuffle' })).toBeVisible();
+    await expect(app.getByRole('button', { name: /^Repeat/ })).toBeVisible();
+    await expect(app.getByRole('button', { name: 'Show the queue' })).toBeVisible();
+  });
+
+  test('sizes what is left for a thumb', async ({ app }) => {
+    for (const name of ['Previous track', 'Next track']) {
+      const [w, h] = await sizeOf(app, name);
+
+      expect(w, `${name} width`).toBeGreaterThanOrEqual(TARGET);
+      expect(h, `${name} height`).toBeGreaterThanOrEqual(TARGET);
+    }
+
+    // Play is deliberately bigger than its neighbours: a row of
+    // identical squares says every action is equally likely, which is
+    // not true of play.
+    const [pw, ph] = await sizeOf(app, PLAY_PAUSE);
+    const [nw] = await sizeOf(app, 'Next track');
+
+    expect(ph).toBeGreaterThanOrEqual(TARGET);
+    expect(pw).toBeGreaterThan(nw);
+  });
+
+  /**
+   * The favourite was 18x14 and is one of the three controls #59
+   * keeps, so it is part of this issue rather than a nicety.
+   */
+  test('sizes the favourite, which was the smallest control in the app', async ({
+    app,
+  }) => {
+    const fav = app
+      .locator('now-playing')
+      .getByRole('button', { name: /Favorites$/ });
+
+    const box = await fav.boundingBox();
+
+    expect(box).not.toBeNull();
+    expect(box!.width).toBeGreaterThanOrEqual(TARGET);
+    expect(box!.height).toBeGreaterThanOrEqual(TARGET);
+  });
+
+  /**
+   * **The route to the queue must not depend on what is playing.**
+   *
+   * `now-playing` renders two branches, and the no-track one had no
+   * `.expand` button on its placeholder — so with nothing loaded there
+   * was no way to Now Playing, and once #59 takes the queue button off
+   * the bar that makes the *queue* unreachable. The queue is persisted
+   * across restarts, so "tracks queued, nothing playing" is a state the
+   * app launches into.
+   *
+   * This is asserted with the queue explicitly emptied rather than by
+   * relying on the app not having played anything: `make e2e` runs one
+   * long-lived app across every spec file (#168), so "no track loaded"
+   * is otherwise whatever the file before this one left behind — which
+   * is how the underlying fault first showed up as a flake in a spec
+   * about something else.
+   */
+  test('reaches the queue with nothing playing', async ({ app }) => {
+    await app.evaluate(async () => {
+      await window.__yjEvents.call('queue.Queue.Clear', [], 10_000);
+    });
+
+    await expect(app.getByTestId('open-now-playing')).toBeVisible();
+
+    await app.getByTestId('open-now-playing').click();
+    await app.getByTestId('npv-queue').click();
+
+    await expect(app.locator('#queue-panel')).toHaveAttribute('open', '');
+  });
+
+  test('still fits, with nothing to scroll sideways to', async ({ app }) => {
+    const fit = await app.evaluate(() => ({
+      scroll: document.body.scrollWidth,
+      client: document.body.clientWidth,
+    }));
+
+    expect(fit.scroll).toBe(fit.client);
+  });
+});
+
+test.describe('the full-screen transport is the page', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await stageATrack(app);
+    await app.getByTestId('open-now-playing').click();
+  });
+
+  test('draws all five, larger than the bar draws any', async ({ app }) => {
+    const [pw, ph] = await sizeOf(app, PLAY_PAUSE);
+
+    expect(pw).toBeGreaterThanOrEqual(56);
+    expect(ph).toBeGreaterThanOrEqual(56);
+
+    for (const name of ['Shuffle', 'Previous track', 'Next track']) {
+      const [w, h] = await sizeOf(app, name);
+
+      expect(w, `${name} width`).toBeGreaterThanOrEqual(TARGET);
+      expect(h, `${name} height`).toBeGreaterThanOrEqual(TARGET);
+    }
+  });
+
+  test('fits at both phone widths', async ({ app }) => {
+    for (const size of [DEVICE, PHONE]) {
+      await app.setViewportSize(size);
+
+      const fit = await app.evaluate(() => ({
+        scroll: document.body.scrollWidth,
+        client: document.body.clientWidth,
+      }));
+
+      expect(fit.scroll, `${size.width}px`).toBe(fit.client);
+    }
+  });
+});
+
+/**
+ * **The desktop bar is not what either issue is about, and must not
+ * move.** Both are `Platform/Android`; this is the guard that says so
+ * in a way a build can check.
+ *
+ * It caught a real regression while it was being written: a generic
+ * `font-size` on the buttons took them from the UA stylesheet's 13.3px
+ * to the shell's 16px and grew every one from 33x21 to 36x24 — a
+ * change nobody asked for, invisible to every other assertion here.
+ */
+test.describe('the desktop bar is untouched', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DESKTOP);
+    await stageATrack(app);
+  });
+
+  test('keeps all five controls and the queue button', async ({ app }) => {
+    const bar = barControls(app);
+
+    for (const name of ['Shuffle', 'Previous track', 'Next track']) {
+      await expect(bar.getByRole('button', { name })).toBeVisible();
+    }
+
+    await expect(bar.getByRole('button', { name: /^Repeat/ })).toBeVisible();
+    await expect(app.locator('#queue-button')).toBeVisible();
+  });
+
+  /**
+   * **The mechanism, because the pixels are the engine's.**
+   *
+   * The first version of this asserted the literal `'33x21'`, measured
+   * on `main` in Chromium — and WebKit draws the same button **36x24**,
+   * so it failed in CI on a build where nothing was wrong. A button's
+   * box comes from the UA stylesheet when the author sets nothing, and
+   * what each UA sets is its own business.
+   *
+   * What this PR must not do is *set* anything here, so that is what is
+   * asserted: our two box properties are unset, and the font is still
+   * the UA's rather than the shell's. That is precisely the regression
+   * this caught the first time — a generic `font-size: inherit` took
+   * these from the UA's default to 16px — and it catches it in either
+   * engine.
+   */
+  test('sets no size of its own on the desktop bar', async ({ app }) => {
+    const measured = await barControls(app).evaluate((el) => {
+      // A bare button with no author styles: whatever this engine
+      // gives one is what the bar's buttons must still be.
+      const probe = document.createElement('button');
+
+      document.body.appendChild(probe);
+
+      const uaFontSize = getComputedStyle(probe).fontSize;
+
+      probe.remove();
+
+      return [...el.shadowRoot!.querySelectorAll('button')].map((b) => {
+        const cs = getComputedStyle(b);
+        const r = b.getBoundingClientRect();
+
+        return {
+          minWidth: cs.minWidth,
+          minHeight: cs.minHeight,
+          usesUaFont: cs.fontSize === uaFontSize,
+          size: `${Math.round(r.width)}x${Math.round(r.height)}`,
+        };
+      });
+    });
+
+    expect(measured).toHaveLength(5);
+
+    for (const m of measured) {
+      expect(m.minWidth, 'min-width').toBe('0px');
+      expect(m.minHeight, 'min-height').toBe('0px');
+      expect(m.usesUaFont, 'font-size is still the UA default').toBe(true);
+    }
+
+    // And all five are the same box: `.play` takes a larger size in
+    // both sized contexts, so this is what says the desktop is neither
+    // of them.
+    expect(new Set(measured.map((m) => m.size)).size).toBe(1);
+  });
+});

e2e/specs/queue-as-a-screen.spec.ts

@@ -0,0 +1,346 @@
+import { test, expect, openTheQueue } from '../support/fixtures.js';
+
+/**
+ * #55 — the queue is a *place* while it covers the content, and a
+ * *control* while it sits beside it.
+ *
+ * #24 already made the pixels right: measured at the reference device's
+ * 424×439, the overlaid panel is 424×318, which is `.main-panel`'s rect
+ * exactly. What was missing was the navigation model, and the defect was
+ * measurable in one line — opening the queue on Artists and pressing
+ * back moved the page *underneath* to Albums and left the queue up. A
+ * back press that changes something the user cannot see, and costs them
+ * their place, is the whole of "it does not flow".
+ *
+ * **These assert the entry, not the attribute.** The temptation is to
+ * check `#queue-button[aria-expanded]` and stop, which is the shell's
+ * own bookkeeping and was right throughout the bug: what has to be true
+ * is that *one* back press closes the queue and the *next* one
+ * navigates. Asserting only the first would pass on a build that
+ * orphans the entry, which is the defect moved one press later — the
+ * same trap `back-navigation.spec.ts` documents about `data-active-view`
+ * and `layout-overflow.spec.ts` set for #69.
+ *
+ * **Three of these nine fail on the build before #55**, and the other
+ * six cannot, which is worth knowing before trusting them: "the entry
+ * is not orphaned" and "the column is not in the stack" are both
+ * vacuously true of a build that pushes no entry at all, and the
+ * containment assertion pins the mount that was *not* taken. They guard
+ * the next change rather than reproducing this one — the three that
+ * reproduce it are the two back-press tests and the touch target.
+ */
+type Page = import('@playwright/test').Page;
+
+/** The reference device's real viewport, not a resized desktop. */
+const DEVICE = { width: 424, height: 439 };
+
+/** Wide enough that the queue is a column: 1280 − 200 − 320 ≥ 480. */
+const DESKTOP = { width: 1280, height: 800 };
+
+/**
+ * The Compact band, where the queue is a *screen* (644 − 320 < 480) and
+ * the bottom bar still carries its button.
+ *
+ * Two of these tests need both facts at once and only this band has
+ * them: below 600px #59 takes the button off the bar, so there is no
+ * toggle to re-press and the queue is opened from Now Playing — which
+ * is itself a detail view, so "the destination stays lit" is vacuously
+ * true there rather than tested.
+ */
+const COMPACT = { width: 700, height: 600 };
+
+const activeView = (page: Page) => page.getByTestId('main-content');
+const queue = (page: Page) => page.locator('#queue-panel');
+const toggle = (page: Page) => page.locator('#queue-button');
+
+/**
+ * Whether the queue is up.
+ *
+ * The panel's own attribute rather than the toggle's `aria-expanded`,
+ * because below 600px there is no toggle to ask (#59) — and the panel
+ * is the one fact both of them reflect anyway.
+ */
+async function expectQueue(page: Page, open: boolean): Promise<void> {
+  const panel = queue(page);
+
+  if (open) {
+    await expect(panel).toHaveAttribute('open', '');
+  } else {
+    await expect(panel).not.toHaveAttribute('open', '');
+  }
+}
+
+test.describe('the queue is a screen where it covers the content', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await app.getByTestId('tab-albums').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+  });
+
+  // On a phone the queue is opened from Now Playing (#59), so the page
+  // *underneath* it is `now-playing` and the journey is two entries
+  // deep: albums -> now-playing -> queue. That is the real route a user
+  // takes, which is why these do not reach for the shortcut.
+
+  test('back closes the queue and leaves the page where it was', async ({
+    app,
+  }) => {
+    await expect(queue(app)).toHaveAttribute('overlay', '');
+
+    await openTheQueue(app);
+    await expectQueue(app, true);
+
+    await app.goBack();
+
+    await expectQueue(app, false);
+    // The page underneath is untouched. Before #55 this was the
+    // *previous* view, because the queue was not in the stack at all
+    // and back spent an entry navigating something nobody could see.
+    await expect(activeView(app)).toHaveAttribute(
+      'data-active-view',
+      'now-playing',
+    );
+  });
+
+  test('costs exactly one entry, so the next press navigates', async ({
+    app,
+  }) => {
+    await openTheQueue(app);
+    await expectQueue(app, true);
+
+    await app.goBack();
+    await expectQueue(app, false);
+    await expect(activeView(app)).toHaveAttribute(
+      'data-active-view',
+      'now-playing',
+    );
+
+    await app.goBack();
+
+    // Exactly one entry each: the second press leaves Now Playing for
+    // the page it was opened from, rather than being swallowed by a
+    // queue that had already closed.
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+  });
+
+  /**
+   * Every route out unwinds the entry, and they do it through the
+   * panel's own `open` attribute rather than each knowing about
+   * history — which is why a fourth route added later gets this free.
+   *
+   * The failure this pins is silent: close by button, and if the entry
+   * is orphaned the app looks correct until the next back press does
+   * nothing at all. It is a guard rather than a reproduction — a build
+   * with no entry to orphan passes it — and it is paired with the two
+   * above, which do reproduce.
+   */
+  for (const [name, dismiss] of [
+    [
+      'the close button',
+      async (app: Page) => {
+        await app.getByRole('button', { name: 'Close queue' }).click();
+      },
+    ],
+    [
+      'Escape',
+      async (app: Page) => {
+        await app.keyboard.press('Escape');
+      },
+    ],
+  ] as Array<[string, (app: Page) => Promise<void>]>) {
+    test(`${name} leaves no entry behind`, async ({ app }) => {
+      await openTheQueue(app);
+      await expectQueue(app, true);
+
+      await dismiss(app);
+      await expectQueue(app, false);
+
+      await app.goBack();
+
+      // One press, one screen: Now Playing is what the queue was opened
+      // from, so leaving it lands on Albums. An orphaned entry would
+      // have spent this press on nothing and left it here.
+      await expect(activeView(app)).toHaveAttribute(
+        'data-active-view',
+        'albums',
+      );
+    });
+  }
+
+  /**
+   * A detail view leaves the destination it was opened from lit
+   * (`active-view-store`, #72), and the queue inherits that — it is
+   * published with `isPrimary: false`, so `isActive('albums')` is still
+   * true underneath it.
+   *
+   * `aria-current` rather than a class, for the reason
+   * `back-navigation.spec.ts` gives: the class was right throughout the
+   * bug that rule exists for.
+   */
+
+  /**
+   * With the panel spanning the whole width the scrim has no uncovered
+   * pixels, so the close button is the only pointer route out of a
+   * full-screen surface. Measured at 424×439 before #55: **25×21px**.
+   */
+  test('offers a way out a thumb can hit', async ({ app }) => {
+    await openTheQueue(app);
+
+    const box = await app
+      .getByRole('button', { name: 'Close queue' })
+      .boundingBox();
+
+    expect(box).not.toBeNull();
+    expect(box!.width).toBeGreaterThanOrEqual(44);
+    expect(box!.height).toBeGreaterThanOrEqual(44);
+  });
+});
+
+/**
+ * **The mechanism, because no tier here can see the consequence.**
+ *
+ * #55's Direction asked for a `DETAIL_LOADERS` mount, which would put
+ * the panel inside `.main-panel > *`. That box is paint-contained under
+ * a `.main-panel` that is too, and `contain: paint` makes an element a
+ * containing block for fixed descendants *and clips them* — which is
+ * what a `wa-popup` falls back to on the reference device's Chrome 113,
+ * where the Popover API does not exist (#60, `.planning/NOTES.md`).
+ * `queue-panel` has a context menu, so that mount would have broken a
+ * working menu on the one device this issue is about.
+ *
+ * CI's Chromium and WebKit both *have* the Popover API, so the menu is
+ * top-layered and correct here either way: a spec asserting "the menu is
+ * not clipped" is green on the broken build. What a browser can answer
+ * honestly is where the element is, so that is what this asks.
+ */
+test('the panel stays out of the paint-contained region', async ({ app }) => {
+  await app.setViewportSize(DEVICE);
+
+  // Open, because that is the only state in which a menu can be opened
+  // from it — and because the host drops `paint` from its own
+  // containment deliberately in overlay mode, so a closed panel answers
+  // a different question.
+  await openTheQueue(app);
+  await expectQueue(app, true);
+
+  const ancestry = await app.evaluate(() => {
+    const chain: Array<{ tag: string; contain: string }> = [];
+
+    for (
+      let el = document.getElementById('queue-panel');
+      el && el !== document.documentElement;
+      el = el.parentElement
+    ) {
+      chain.push({
+        tag: el.tagName.toLowerCase(),
+        contain: getComputedStyle(el).contain,
+      });
+    }
+
+    return chain;
+  });
+
+  expect(ancestry.length).toBeGreaterThan(1);
+  expect(ancestry.some((a) => a.tag === 'main')).toBe(false);
+
+  for (const { tag, contain } of ancestry) {
+    expect(
+      `${tag}: ${contain}`,
+      'a paint-contained ancestor clips a fixed-positioned popup on Chrome 113',
+    ).not.toMatch(/paint|content|strict/);
+  }
+});
+
+/**
+ * Two properties need the queue to be a *screen* and the bar to still
+ * have its button, and only the Compact band has both — below 600px #59
+ * takes the button off the bar.
+ */
+test.describe('a screen opened from the bar', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(COMPACT);
+    await app.getByTestId('nav-albums').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    await expect(queue(app)).toHaveAttribute('overlay', '');
+  });
+
+  /**
+   * A detail view leaves the destination it was opened from lit
+   * (`active-view-store`, #72), and the queue inherits that — it is
+   * published with `isPrimary: false`, so `isActive('albums')` is still
+   * true underneath it.
+   *
+   * `aria-current` rather than a class, for the reason
+   * `back-navigation.spec.ts` gives: the class was right throughout the
+   * bug that rule exists for.
+   */
+  test('leaves the destination it was opened from highlighted', async ({
+    app,
+  }) => {
+    // By testid, not by role: at 700px the sidebar is in icon mode, so
+    // what the item is *named* is a different question from which item
+    // it is. The assertion is still `aria-current`, which is the
+    // accessible fact.
+    const albums = app.getByTestId('nav-albums');
+
+    await expect(albums).toHaveAttribute('aria-current', 'page');
+
+    await toggle(app).click();
+    await expectQueue(app, true);
+
+    await expect(albums).toHaveAttribute('aria-current', 'page');
+  });
+
+  /** The toggle is a fourth way out, and it unwinds the entry like the
+   *  other three — through the panel's attribute, not its own handler. */
+  test('closes from the same toggle, leaving no entry behind', async ({
+    app,
+  }) => {
+    await toggle(app).click();
+    await expectQueue(app, true);
+
+    await toggle(app).click();
+    await expectQueue(app, false);
+
+    await app.goBack();
+
+    await expect(activeView(app)).not.toHaveAttribute(
+      'data-active-view',
+      'albums',
+    );
+  });
+});
+
+/**
+ * The column is not a place. Somebody docked it; back must not undock
+ * it, and navigating to another view must not take it away.
+ *
+ * This is the half a viewport breakpoint would get wrong: the mode is
+ * computed from the panel's own drag-resizable width, so the queue
+ * becomes a screen exactly when it stops being affordable as a column.
+ */
+test.describe('a docked queue is not in the back stack', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DESKTOP);
+  });
+
+  test('survives a navigation, and back navigates the page', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-albums').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+
+    await toggle(app).click();
+    await expectQueue(app, true);
+    await expect(queue(app)).not.toHaveAttribute('overlay', '');
+
+    await app.getByTestId('nav-artists').click();
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'artists');
+    await expectQueue(app, true);
+
+    await app.goBack();
+
+    await expect(activeView(app)).toHaveAttribute('data-active-view', 'albums');
+    await expectQueue(app, true);
+  });
+});

e2e/specs/queue-overlay.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, openTheQueue } from '../support/fixtures.js';
 
 /**
  * #24 — the queue panel does not take the page's width away from it.
@@ -54,15 +54,15 @@ const shellGeometry = (page: import('@playwright/test').Page) =>
     };
   });
 
-async function openQueue(page: import('@playwright/test').Page) {
+/**
-  const toggle = page.locator('#queue-button');
+ * Opening the queue is `openTheQueue`, which takes the route this
-
+ * viewport offers. It used to be a local helper that clicked
-  if ((await toggle.getAttribute('aria-expanded')) !== 'true') {
+ * `#queue-button` unconditionally, and #59 hid that button below
-    await toggle.click();
+ * 600px -- so the two phone bands here failed on a build where the
-  }
+ * queue was working perfectly, having been asserting *how* it opens as
-
+ * much as what it does.
-  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ */
-}
+const openQueue = openTheQueue;
 
 test.describe('an open queue leaves the content its width', () => {
   for (const band of BANDS) {

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,269 @@
+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 kept, and what it asks changed with #57.** There is no bar
+ * to fit below 600px any more — it is out of the grid and visually
+ * hidden — so "nothing hangs out of it" is a claim about an element
+ * with no row, and would pass on a build that had merely broken the
+ * bar. Dropping the width would be dropping the one place this file
+ * can still say something true about a phone, so it asserts the
+ * *stronger* property instead, below: the bar is out of the layout
+ * altogether, which is the thing #57 wanted and the thing that makes
+ * fitting moot.
+ */
+const WIDTHS = [600, 800, 899, 900, 1440];
+
+/** Where #57 leaves the bar, and where the desktop still has one. */
+const PHONE_WIDTH = 390;
+
+/**
+ * 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', () => {
+  /**
+   * The phone's answer, which is not "it fits" (#57).
+   *
+   * The bar has no grid row below 600px, so measuring its children
+   * against its content box is measuring a 1px box that is already
+   * invisible — a fit pass would collapse the wordmark every time and
+   * report success about nothing, which is why `measureTopBarFit`
+   * declines to run at all when the bar is out of flow. What is worth
+   * asserting here is that the fit pass has not quietly started
+   * *undoing* that: a rule that put the bar back in the layout would
+   * pass every assertion in this file and cost a 439px screen 12% of
+   * its height.
+   */
+  test(`the bar is out of the layout at ${PHONE_WIDTH}px, with a job running`, async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize({ width: PHONE_WIDTH, height: 600 });
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+
+    // Not merely hidden: `display: none` on the header would satisfy
+    // "invisible" and leave the 3.25em row exactly where it was. So
+    // the assertion is that the content starts where the row above it
+    // ends -- and with a job staged, the row above it is the jobs
+    // band, which is the whole reason this row could go.
+    await expect
+      .poll(() =>
+        app.evaluate(() => {
+          const bar = document.querySelector<HTMLElement>('header.top-bar')!;
+          const main = document.querySelector<HTMLElement>('.main-panel')!;
+          const band = document.querySelector<HTMLElement>('job-band')!;
+
+          return {
+            position: getComputedStyle(bar).position,
+            gap:
+              Math.round(main.getBoundingClientRect().top) -
+              Math.round(band.getBoundingClientRect().bottom),
+          };
+        }),
+      )
+      .toEqual({ position: 'absolute', gap: 0 });
+
+    // And the work is still visible, in the band that replaced the
+    // indicator (#62) — which is what made this row removable at all.
+    await expect(app.locator('job-indicator')).toBeHidden();
+    await expect(app.locator('job-band').locator('job-row')).toHaveCount(1);
+
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  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.
+      await expect(app.locator('job-indicator')).toBeVisible();
+
+      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,79 @@ 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' });
+}
+
+/**
+ * Open the queue the way a user at this viewport would.
+ *
+ * **The route differs by width and that is the feature, not an
+ * inconvenience.** Above 600px the bottom bar carries a queue button.
+ * Below it that button is gone (#59) and the queue is reached from the
+ * full-screen Now Playing view, which the mini player's art opens —
+ * "reachable only from Now Playing", which is what the issue asks for.
+ *
+ * It is here rather than in one spec because four files need it, and
+ * because a spec that hard-codes `#queue-button` is quietly asserting
+ * *which* route exists as well as what the queue does. Four of them
+ * were, which is how hiding one button failed ten tests about
+ * something else.
+ *
+ * The width is read from the page rather than passed, so a caller that
+ * resizes and then opens does not have to say so twice.
+ */
+export async function openTheQueue(page: Page): Promise<void> {
+  const toggle = page.locator('#queue-button');
+
+  if (await toggle.isVisible()) {
+    if ((await toggle.getAttribute('aria-expanded')) !== 'true') {
+      await toggle.click();
+    }
+
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    return;
+  }
+
+  // The phone: through Now Playing. `open-now-playing` is the mini
+  // player's art, which is a button only below 600px.
+  if (
+    (await page.getByTestId('main-content').getAttribute('data-active-view')) !==
+    'now-playing'
+  ) {
+    await page.getByTestId('open-now-playing').click();
+  }
+
+  await page.getByTestId('npv-queue').click();
+  await expect(page.locator('#queue-panel')).toHaveAttribute('open', '');
+}
+
 /** Thin client for the dev-only /__test/ surface (backend/testctl). */
 export class TestCtl {
   constructor(private readonly baseURL: string) {}

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/player/player.ts

@@ -142,6 +142,18 @@ export function SetVolume(desiredVolume: $models.UserVolume): $CancellablePromis
     return $Call.ByID(1375836663, desiredVolume);
 }
 
+/**
+ * SystemOwnsVolume reports whether the platform's own control is the
+ * only volume control there is, so this app neither offers one nor
+ * remembers a level.
+ * 
+ * It is bound: the frontend renders no `<volume-control>` when it is
+ * true, at any width.
+ */
+export function SystemOwnsVolume(): $CancellablePromise<boolean> {
+    return $Call.ByID(1027623185);
+}
+
 /**
  * TrackLengthInSeconds returns the duration of the current track.
  */

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;
@@ -297,8 +412,18 @@ body div.sidebar {
    =================================================================== */
 @media (max-width: 599px) {
     body {
+        /* **There is no top-bar row here (#57).** Every one of the five
+           things that bar held has somewhere else to be below 600px:
+           `nav-history` is the platform's own gesture (gone from 899
+           down), the job indicator is `<job-band>` (#62), the search
+           box is a modal opened from the view's own header
+           (`search-trigger`), the library filter is Settings ->
+           Libraries (#148), and the wordmark is below. That is 3.25em
+           of a 439 CSS px viewport -- the single biggest vertical win
+           available on the reference device, which is why #57 asks for
+           the row rather than for a smaller bar. */
         grid-template:
-            "top-bar" 3.25em
+            "jobs-band" auto
             "main-panel" 1fr
             "bottom-bar" auto
             "bottom-nav" auto
@@ -317,40 +442,55 @@ body div.sidebar {
         grid-area: bottom-nav;
     }
 
-    /* The 2em gutters are half a thumb each at this width, and the
+    /* The bar is out of the layout, and out of it the way the *wordmark*
-       subtitle is already gone from 900 down.
+       already goes at desktop widths: visually hidden rather than
+       `display: none`, because that `h1` is the document's top-level
+       heading and this app would otherwise have none on the pages whose
+       own header is empty by design (`page-header` renders no `h1` when
+       `heading` is '', and Settings has no `page-header` at all).
 
-       `min-width: 0` is the load-bearing half. A grid item's implicit
+       Its four *controls* are `display: none` below, which is what
-       minimum is `auto` -- its content -- so a header whose children
+       keeps them out of the tab order -- a visually-hidden container is
-       ask for 580px makes the *body* 580px wide inside a 360px
+       still focusable, and tabbing into a search box nobody can see is
-       viewport, and `overflow-x: hidden` then hides the right-hand
+       worse than not having one.
-       third of the app rather than fitting it. Every box between the
+
-       viewport and the content that must shrink needs this. */
+       This is `styles/sr-only.css.ts`'s recipe again, written out
+       because that one is a `CSSResult` for shadow roots and this is
+       the light DOM. `position: absolute` is also what tells
+       `services/top-bar-fit.ts` there is no row to fit into. */
     .top-bar {
-        padding-left: 0.75em;
+        position: absolute;
-        padding-right: 0.75em;
+        width: 1px;
-        gap: 0.5em;
+        height: 1px;
-        min-width: 0;
+        padding: 0;
+        margin: -1px;
         overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+        border: 0;
+        gap: 0;
+        min-width: 0;
     }
 
+    .top-bar nav-history,
+    .top-bar library-filter,
+    .top-bar search-bar,
+    .top-bar job-indicator {
+        display: none;
+    }
+
+    /* `min-width: 0` is load-bearing wherever a box sits between the
+       viewport and content that must shrink. A grid item's implicit
+       minimum is `auto` -- its content -- so one child insisting on
+       580px makes the *body* 580px wide inside a 360px viewport, and
+       `overflow-x: hidden` then hides the right-hand third of the app
+       rather than fitting it. */
     .content-area,
     .main-panel,
     .bottom-bar {
         min-width: 0;
     }
 
-    .title {
-        font-size: 1.1em;
-    }
-
-    /* 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. */
-    .top-bar library-filter {
-        display: none;
-    }
-
     /* The full-screen now-playing view *is* the transport, so the bar
        repeating it underneath is 4em of a small screen spent saying
        the same thing twice -- visible in a screenshot, invisible to
@@ -364,14 +504,14 @@ body div.sidebar {
     body:has(#main-content[data-active-view="now-playing"]) .bottom-bar {
         display: none;
     }
-
-    .top-bar search-bar {
-        flex: 1 1 auto;
-        min-width: 0;
-    }
 }
 
 @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;
@@ -380,4 +520,85 @@ body div.sidebar {
     .bottom-bar audio-player {
         margin: 0.25em;
     }
+
+    /* Volume stands down here whatever the setting says, because this
+       is about room: five controls and a slider do not fit a 360px
+       bar, and the full-screen now-playing view is where seeking and
+       volume go on a phone. 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.
+
+       **This rule used to carry the platform argument too, and no
+       longer does** (#64). "The hardware keys own the volume" is not a
+       width: it is false of a narrow desktop window and true of an
+       Android tablet, which this selector gets backwards both ways.
+       The player answers it now — `SystemOwnsVolume` — and
+       `volume-control` renders nothing when it is true, at every
+       width and in both of its mount points. What is left here is the
+       question a stylesheet can actually answer. */
+    .bottom-bar volume-control {
+        display: none;
+    }
+
+    /* The queue leaves the phone's bar (#59), because #55 made it a
+       screen with an entry in the back stack and Now Playing already
+       carries its own button for it. The route is the mini player's
+       art -> Now Playing -> the queue, which is the "reachable only
+       from Now Playing" this issue asks for.
+
+       This is allowed to remove a control only because the control is
+       still reachable: plan 018's matrix promises that no action is
+       ever unreachable at any supported size, and that promise is what
+       `phone-transport.spec.ts` asserts rather than the button count.
+
+       **`.bottom-bar #queue-button`, not `#queue-button`**, and that is
+       not decoration. The rule this overrides is written *nested*
+       inside `.bottom-bar`, so it builds to a descendant selector one
+       class more specific than it looks in the source -- and a bare
+       `#queue-button` here loses to it, media query or not. Being last
+       in the file is not enough when the thing above is more specific,
+       which is the same lesson as this section's own header one level
+       down: nesting adds specificity the source does not show, and the
+       failure is silent (the button simply stayed). */
+    .bottom-bar #queue-button {
+        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.
+
+   #57 has since done exactly that, so the indicator's own rule now
+   lives with the other three in the phone block above, where the bar
+   goes out of the layout in one statement rather than four. What stays
+   here is the band, and the argument for it.  */
+@media (max-width: 599px) {
+    /* The indicator's 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

@@ -14,16 +14,37 @@
          user is not walked through the header, the library filter, the
          search box and eleven nav items on every navigation. -->
     <a class="skip-link" href="#main-content">Skip to content</a>
+    <!-- Below 600px this bar is not in the layout at all (#57): index.css
+         takes its grid row away and leaves the element visually hidden,
+         carrying nothing but the `h1` below.  Every control in it has
+         somewhere else to be there -- `nav-history` is the platform's
+         own back gesture, `job-indicator` is `<job-band>`, `search-bar`
+         is `<search-dialog>` opened from the view's own header, and
+         `library-filter` is Settings -> Libraries (#148). -->
     <header class="top-bar">
         <hgroup>
             <h1 class="title">YellowJacket</h1>
             <!-- 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,16 +55,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"
+        <div class="bar-end">
-            id="queue-button">
+            <volume-control></volume-control>
-            <!-- ICON_QUEUE in src/utils/icon-language.ts, written out
+            <button aria-label="Toggle queue" aria-controls="queue-panel" aria-expanded="false"
-                 because this file has no module scope. It was `list`,
+                id="queue-button">
-                 which is the Playlists destination's icon. -->
+                <!-- ICON_QUEUE in src/utils/icon-language.ts, written out
-            <wa-icon name="bars-staggered"></wa-icon>
+                     because this file has no module scope. It was `list`,
-        </button>
+                     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
@@ -55,6 +91,12 @@
     <first-run-wizard></first-run-wizard>
     <notification-host></notification-host>
     <shortcuts-overlay></shortcuts-overlay>
+    <!-- The phone's search surface (#57).  A singleton here for the
+         reason shortcuts-overlay is one: one instance, one document
+         listener, and no `data-testid="search-input"` resolving to two
+         elements.  It renders nothing while shut, so the header's box
+         is still the only one on a desktop. -->
+    <search-dialog></search-dialog>
 </body>
 
 </html>

frontend/index.ts

@@ -18,12 +18,21 @@
 //   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';
+// The phone's search surface (#57). Eager, because below 600px it is
+// the *only* way to search and a modal that has to fetch a chunk before
+// it can take a keystroke is late by exactly the interval it exists to
+// remove. It renders nothing until asked.
+import '@components/search-dialog/search-dialog.ts';
 import '@components/library-filter/library-filter.ts';
 import '@components/first-run-wizard/first-run-wizard.ts';
 import '@components/notifications/notification-host.ts';
@@ -34,12 +43,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 +67,8 @@ import '@store/theme-store';
 import './src/services/keyboard-shortcut-service';
 import { activateView, deactivateView } from '@utils/view-lifecycle';
 import { installLongPressContextMenu } from '@utils/long-press';
+import { openQueue, queuePanelElement } from '@utils/open-queue';
+import { installTopBarFit } from './src/services/top-bar-fit';
 import {
     hasTrackPayload,
     getDragPayload,
@@ -70,6 +88,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 +124,6 @@ const VIEW_TAGS: Record<string, string> = {
     explore: 'explore-view',
     autotag: 'autotag-view',
     downloads: 'downloads-view',
-    jobs: 'jobs-view',
     settings: 'config-page',
 };
 
@@ -116,7 +141,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,49 +238,132 @@ 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
+/** The navigation an entry stands for, and where it sits in this
- *  predates the app's own routing, which is the one back exits from. */
+ *  session's list. `undefined` on the entry that predates the app's own
-type NavState = { yjNav?: { view: string; [key: string]: any } };
+ *  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 --
+// Back and forward are the *same* `popstate` event -- it carries no
- *  i.e. how deep back can go while staying inside the app. */
+// direction, and the History API exposes neither the current position
-let pushedEntries = 0;
+// 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
+    // `_isBack` and `_replace` are bookkeeping, not destination: keeping
-    // would make a replayed navigation claim to be a back-navigation.
+    // either in the entry would make a replayed navigation claim to be
-    const { _isBack: _ignored, ...nav } = detail;
+    // one.
-    const state: NavState = { yjNav: nav };
+    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, '');
+        currentIndex += 1;
-        pushedEntries += 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 });
 });
 
+/**
+ * The queue, while it is a screen (#55).
+ *
+ * It is *not* in `VIEW_TAGS` and *not* in `DETAIL_LOADERS`: there is
+ * nothing to mount, because the panel is already in the document and,
+ * as an overlay, already occupies `.main-panel`'s rect exactly. What a
+ * navigation adds is the two things that make a screen a screen — a
+ * history entry, so the platform's back gesture answers it, and a
+ * destination to leave, so navigating anywhere else takes it away.
+ *
+ * Keeping it out of both tables is what keeps its context menu working
+ * on the reference device: `.main-panel > *` is paint-contained and a
+ * `wa-popup` falls back to `position: fixed` on Chrome 113, which
+ * escapes overflow but not containment (#60). The panel stays in
+ * `.content-area`, which is not paint-contained, exactly as it is
+ * today.
+ */
+const QUEUE_VIEW = 'queue';
+
+/** Close a queue that is being navigated away from. A *column* is not
+ *  a place, so it survives a navigation the way the sidebar does. */
+function dismissQueueScreen(): void {
+    const panel = queuePanelElement();
+
+    if (panel?.hasAttribute('overlay')) panel.removeAttribute('open');
+}
+
 async function handleNavigate(
     detail: { view: string; [key: string]: any },
 ): Promise<void> {
@@ -268,6 +375,25 @@ async function handleNavigate(
 
     if (!detail._isBack) recordNavigation(detail);
 
+    if (view === QUEUE_VIEW) {
+        // The shell says where the user is; `false` because the queue is
+        // not a primary view, so nothing in either nav lights while it
+        // is up -- the same rule a detail view gets, and the reason the
+        // tab the queue was opened from stays lit.
+        activeViewStore.setView(view, false);
+        queuePanelElement()?.setAttribute('open', '');
+
+        // Deliberately not `searchStore.setCurrentView` and not
+        // `dataset.activeView`: both describe what is *in the main
+        // panel*, and the queue covers that panel without replacing it.
+        // Overwriting either would disable the search box belonging to
+        // the page underneath and make every `data-active-view`
+        // selector in the suite disagree with the element it names.
+        return;
+    }
+
+    dismissQueueScreen();
+
     // Bookkeeping stays synchronous with the click: the search box's
     // scope and the active-view attribute describe the navigation that
     // was *asked for*, and are what the rest of the app and the e2e
@@ -279,6 +405,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
@@ -497,7 +637,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'
@@ -507,14 +658,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 },
         }));
     });
 
@@ -524,13 +678,17 @@ const queuePanel = document.getElementById('queue-panel') as HTMLElement | null;
 
 if (queueButton && queuePanel) {
     queueButton.addEventListener('click', () => {
-        const isOpen = queuePanel.hasAttribute('open');
+        if (queuePanel.hasAttribute('open')) {
-
+            // Closing goes through the panel either way; where the queue
-        if (isOpen) {
+            // is a screen the observer below is what unwinds its history
+            // entry, so this button, Escape, the scrim and the close
+            // button all take the same route out.
             queuePanel.removeAttribute('open');
-        } else {
+
-            queuePanel.setAttribute('open', '');
+            return;
         }
+
+        openQueue();
     });
 
     // The button says whether the panel is open, and it learns that
@@ -548,7 +706,39 @@ if (queueButton && queuePanel) {
         );
     };
 
-    new MutationObserver(reflectQueueState).observe(queuePanel, {
+    /**
+     * Keep the back stack honest about a queue that closed itself.
+     *
+     * Where the queue is a screen its `open` attribute and the current
+     * history entry are two statements of one fact, and the panel can
+     * change its half on its own -- Escape, the scrim, the close button,
+     * and anything added later. Reconciling here rather than at each of
+     * those is the same reason this observer already exists for
+     * `aria-expanded`: the attribute is the one fact, and a state kept
+     * beside a click is right until something else changes it.
+     *
+     * Without this the entry is orphaned and the *next* back press is
+     * the one that closes the queue -- a press that appears to do
+     * nothing, which is the defect this issue is about, moved one press
+     * later.
+     *
+     * `history.back()` rather than a stack of our own, for the reason
+     * `navigate-back` does: two stacks is how a component's own way out
+     * and the phone's gesture come to disagree about what one press
+     * means.
+     */
+    const reconcileQueueHistory = () => {
+        if (queuePanel.hasAttribute('open')) return;
+
+        const state = history.state as NavState | null;
+
+        if (state?.yjNav?.view === QUEUE_VIEW) history.back();
+    };
+
+    new MutationObserver(() => {
+        reflectQueueState();
+        reconcileQueueHistory();
+    }).observe(queuePanel, {
         attributes: true,
         attributeFilter: ['open'],
     });

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/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

@@ -26,14 +26,15 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
 import { RovingGridController } from '@utils/roving-grid';
 
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@components/playlist-picker/playlist-picker.js';
 import { dict, list } from '@utils/binding';
@@ -131,17 +132,17 @@ export class ArtistsView
     private contextMenuArtistId: number | null = null;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
     getPlaylistSubmenuPopup():
-        | WaPopup
+        | MenuTarget
         | undefined {
         return this.playlistSubmenuPopup;
     }
@@ -1336,11 +1337,8 @@ export class ArtistsView
 
     private renderContextMenu() {
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .contextMenuOpen}
             >
@@ -1434,13 +1432,12 @@ export class ArtistsView
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .playlistSubmenuOpen}
             >
@@ -1468,7 +1465,7 @@ export class ArtistsView
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 

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/controls/player-controls.ts

@@ -1,22 +1,77 @@
-import { LitElement, html, css } from 'lit';
+import { LitElement, html, css, nothing } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
+import { customElement, property, state } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { PlayerController } from '@store/controllers/player-controller';
 import { queueStore } from '@store/queue-store';
 import type { RepeatMode } from '@store/queue-store';
 import { designTokens } from '../../../styles/tokens.css';
+import { PHONE_QUERY } from '../../../utils/breakpoints';
+
+/**
+ * The transport, in the two places it appears.
+ *
+ * **The context is a property and cannot be a media query**, which is
+ * the whole reason this exists (#56). Everywhere else in this app a
+ * component states what it drops at phone width itself, because a media
+ * query inside a shadow root is answered by the viewport and that is
+ * the honest signal. Here the two hosts want *different* answers at the
+ * *same* viewport: on a phone the bottom bar wants three controls sized
+ * for a thumb, and `now-playing-view` wants five, larger still. So the
+ * host says which context and the viewport says which size band, and
+ * neither one alone can express it.
+ *
+ * Measured at the reference device's 424x439 before this: every button
+ * here was **33x21px**, in both places, which is what #56 reports as
+ * "the most important thing in the mobile app and they are tiny".
+ */
+export type ControlsContext = 'bar' | 'full';
 
 @customElement('player-controls')
 export class PlayerControls extends LitElement {
   private player = new PlayerController(this);
   private unsubscribeQueue?: () => void;
 
+  /**
+   * Where these controls are drawn. `bar` is the bottom bar in both
+   * bands; `full` is the full-screen transport.
+   *
+   * Reflected so a spec can read it and so the stylesheet keys off one
+   * fact rather than a class the host has to remember to set.
+   */
+  @property({ type: String, reflect: true })
+  context: ControlsContext = 'bar';
+
   @state() private shuffleMode = false;
   @state() private repeatMode: RepeatMode = 'off';
 
+  /**
+   * Phone width, from `matchMedia` rather than from a media query,
+   * because what it decides is whether shuffle and repeat *exist* here
+   * — and a stylesheet can only decide whether they are painted.
+   * `job-band` and `search-trigger` are the same pattern for the same
+   * reason.
+   */
+  @state() private phone = false;
+
+  private media?: MediaQueryList;
+
+  private onMedia = (e: MediaQueryListEvent) => {
+    this.phone = e.matches;
+  };
+
+  /** Whether this is the phone's bottom bar, which carries three
+   *  controls rather than five. */
+  private get slim(): boolean {
+    return this.context === 'bar' && this.phone;
+  }
+
   override connectedCallback(): void {
     super.connectedCallback();
 
+    this.media = window.matchMedia(PHONE_QUERY);
+    this.phone = this.media.matches;
+    this.media.addEventListener('change', this.onMedia);
+
     const s = queueStore.getState();
     this.shuffleMode = s.shuffleMode;
     this.repeatMode = s.repeatMode;
@@ -37,6 +92,7 @@ export class PlayerControls extends LitElement {
   override disconnectedCallback(): void {
     super.disconnectedCallback();
     this.unsubscribeQueue?.();
+    this.media?.removeEventListener('change', this.onMedia);
   }
 
   static override styles = [designTokens, css`
@@ -58,6 +114,99 @@ export class PlayerControls extends LitElement {
       justify-content: center;
     }
 
+    /* ---------------------------------------------------------------
+       Sizes (#56).
+
+       44px is the floor everything here is sized to, and play/pause
+       alone goes above it -- "large play/pause, adequate prev/next" is
+       the Direction, and it is the one control the report calls "front
+       and centre".
+
+       They are stated as custom properties rather than on each button
+       so a context sets two numbers instead of five rules, and so the
+       icon scales with its target: a 44px box around a 16px glyph is a
+       big hit area that still looks tiny, which is half of what the
+       report is about.
+
+       **The desktop bar sets none of them and must not change at all.**
+       #56 is an Android issue; the desktop's buttons are 33x21 before
+       this and are 33x21 after it.
+
+       That is why the box rules take a zero fallback and the *font-size*
+       rules are scoped to the two contexts instead of sharing them. A
+       button does not inherit its font from its parent -- the UA
+       stylesheet gives it one -- so a generic font-size: inherit is
+       not the no-op it reads as: it moved the desktop's buttons from
+       33x21 to 36x24, silently, by taking them from the UA's 13.3px to
+       the shell's 16px. Measured before and after by stashing this
+       file, which is the only way that particular 3px shows up.
+       --------------------------------------------------------------- */
+    button {
+      min-width: var(--yj-control-target, 0);
+      min-height: var(--yj-control-target, 0);
+    }
+
+    button.play {
+      min-width: var(--yj-control-play-target, 0);
+      min-height: var(--yj-control-play-target, 0);
+    }
+
+    /* The phone's bottom bar: three controls, sized for a thumb.
+       Shuffle and repeat are not here -- see the render method, which
+       does not draw them rather than hiding them, because a control
+       that is display:none is still a thing the component claims to
+       have. They are on the full-screen view, which is one tap away
+       through the mini player's art (#59). */
+    @media (max-width: 599px) {
+      :host([context='bar']) {
+        --yj-control-target: 44px;
+        --yj-control-icon: 18px;
+        --yj-control-play-target: 56px;
+        --yj-control-play-icon: 24px;
+      }
+
+      :host([context='bar']) button {
+        font-size: var(--yj-control-icon);
+      }
+
+      :host([context='bar']) button.play {
+        font-size: var(--yj-control-play-icon);
+      }
+    }
+
+    /* The full-screen transport, at every width: this view *is* the
+       player, so the controls are the page rather than a strip of it. */
+    :host([context='full']) {
+      --yj-control-target: 44px;
+      --yj-control-icon: 20px;
+      --yj-control-play-target: 64px;
+      --yj-control-play-icon: 28px;
+    }
+
+    :host([context='full']) button {
+      font-size: var(--yj-control-icon);
+    }
+
+    :host([context='full']) button.play {
+      font-size: var(--yj-control-play-icon);
+    }
+
+    :host([context='full']) #player-control-buttons {
+      gap: 12px;
+    }
+
+    /* Secondary controls sit below the primary row rather than beside
+       it, which is the Direction's shape and is why this is a second
+       group in the DOM instead of a CSS order property: visual order
+       and focus order have to agree. */
+    .secondary {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      gap: 24px;
+      margin-top: 8px;
+    }
+
     button:hover {
       color: var(--yj-accent-text, #ffd43b);
     }
@@ -104,46 +253,107 @@ export class PlayerControls extends LitElement {
     queueStore.cycleRepeat();
   };
 
-  override render() {
+  /** Shuffle. Secondary: it changes how the queue behaves rather than
-    const playOrPauseIcon = this.player.isPlaying ? 'pause' : 'play';
+   *  what is playing now. */
-    const playOrPauseHandler = this.player.isPlaying
+  private renderShuffle() {
-      ? this.handlePauseClick
+    return html`
-      : this.handlePlayClick;
+      <button
+        class=${this.shuffleMode ? 'active' : ''}
+        aria-label="Shuffle"
+        aria-pressed=${this.shuffleMode}
+        @click=${this.handleShuffleClick}
+      >
+        <wa-icon name="shuffle"></wa-icon>
+      </button>
+    `;
+  }
 
-    const shuffleClass = this.shuffleMode ? 'active' : '';
+  /** Repeat, whose label spells the mode out because one icon covers
+   *  three states. */
+  private renderRepeat() {
     const repeatMode = this.repeatMode;
     const repeatClasses = [
       repeatMode !== 'off' ? 'active' : '',
       repeatMode === 'one' ? 'repeat-one' : '',
     ].filter(Boolean).join(' ');
 
+    return html`
+      <button
+        class=${repeatClasses}
+        aria-label=${`Repeat: ${repeatMode}`}
+        aria-pressed=${repeatMode !== 'off'}
+        @click=${this.handleRepeatClick}
+      >
+        <wa-icon name="repeat"></wa-icon>
+      </button>
+    `;
+  }
+
+  /** Previous, play/pause, next — the three that are always drawn, in
+   *  every context and at every width. Only play/pause takes the large
+   *  size: the Direction asks for "large play/pause, adequate
+   *  prev/next", and a row of identical squares says every action here
+   *  is equally likely, which is not true of play. */
+  private renderPrimary() {
+    const playOrPauseIcon = this.player.isPlaying ? 'pause' : 'play';
+    const playOrPauseHandler = this.player.isPlaying
+      ? this.handlePauseClick
+      : this.handlePlayClick;
+
+    return html`
+      <button
+        aria-label="Previous track"
+        @click=${this.handlePreviousClick}
+      >
+        <wa-icon name="backward-step"></wa-icon>
+      </button>
+      <button
+        class="play"
+        aria-label=${this.player.isPlaying ? 'Pause' : 'Play'}
+        @click="${playOrPauseHandler}"
+      >
+        <wa-icon name=${playOrPauseIcon}></wa-icon>
+      </button>
+      <button
+        aria-label="Next track"
+        @click=${this.handleNextClick}
+      >
+        <wa-icon name="forward-step"></wa-icon>
+      </button>
+    `;
+  }
+
+  /**
+   * Two arrangements, not two components.
+   *
+   * `bar` keeps the order it has always had — shuffle, prev, play,
+   * next, repeat, one row — so nothing about the desktop bar moves.
+   * `full` puts the primary three on their own row with the secondary
+   * pair beneath, which the Direction asks for.
+   *
+   * **The phone's bar draws three buttons rather than hiding two.** A
+   * `display: none` control is still in the component's shadow root,
+   * still in the accessibility tree's markup, and still something a
+   * `shadowAll('button')[4]` finds — so "the phone has three controls"
+   * would be true of the pixels and false of the element. They are
+   * reachable on the full-screen view, which the mini player's art
+   * opens, and through the global shortcuts.
+   */
+  override render() {
+    if (this.context === 'full') {
+      return html`
+        <div id="player-control-buttons">${this.renderPrimary()}</div>
+        <div class="secondary">
+          ${this.renderShuffle()}${this.renderRepeat()}
+        </div>
+      `;
+    }
+
     return html`
       <div id="player-control-buttons">
-        <button
+        ${this.slim ? nothing : this.renderShuffle()}
-          class=${shuffleClass}
+        ${this.renderPrimary()}
-          aria-label="Shuffle"
+        ${this.slim ? nothing : this.renderRepeat()}
-          aria-pressed=${this.shuffleMode}
-          @click=${this.handleShuffleClick}
-        >
-          <wa-icon name="shuffle"></wa-icon>
-        </button>
-        <button aria-label="Previous track" @click=${this.handlePreviousClick}>
-          <wa-icon name="backward-step"></wa-icon>
-        </button>
-        <button aria-label=${this.player.isPlaying ? 'Pause' : 'Play'} @click="${playOrPauseHandler}">
-          <wa-icon name=${playOrPauseIcon}></wa-icon>
-        </button>
-        <button aria-label="Next track" @click=${this.handleNextClick}>
-          <wa-icon name="forward-step"></wa-icon>
-        </button>
-        <button
-          class=${repeatClasses}
-          aria-label=${`Repeat: ${repeatMode}`}
-          aria-pressed=${repeatMode !== 'off'}
-          @click=${this.handleRepeatClick}
-        >
-          <wa-icon name="repeat"></wa-icon>
-        </button>
       </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
+    // One owner for the interval, and this is it.  Every other place
-    if (this.isPlaying && this.hasTrack) {
+    // 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 endDrag = () => {
-  private handleInput() {
+    document.removeEventListener('pointerup', this.endDrag);
-    this.stopProgress();
+    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

@@ -1,9 +1,10 @@
-import { LitElement, html, css } from 'lit';
+import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state } from 'lit/decorators.js';
 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,32 @@ 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;
+
+  /**
+   * Whether there is a volume of ours to control at all (#64).
+   *
+   * The decision is made here rather than at either mount point,
+   * because there are two -- the bottom bar's copy lives in
+   * `index.html`, which has no module scope to make it conditional --
+   * and one of them is a control the shell cannot un-render. So the
+   * control answers for itself, and the bar and the phone's
+   * full-screen transport get the same answer without either knowing
+   * the question exists.
+   *
+   * It renders `nothing` *and* hides the host: an empty shadow root is
+   * what stops a positional or role query finding a button that cannot
+   * act, and `:host([hidden])` is what stops the element occupying a
+   * flex item's worth of the transport -- the `:host` display above
+   * outranks the UA's `[hidden]` rule, so it has to be said.
+   */
+  @state()
+  private available = volumeStyleStore.available;
+
+  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
@@ -36,6 +63,13 @@ export class VolumeControl extends LitElement {
       align-items: center;
     }
 
+    /* See the available field. A gap is only drawn between boxes,
+       so a hidden host costs its parent nothing -- which is where the
+       29px this gives back to Now Playing comes from (#172). */
+    :host([hidden]) {
+      display: none;
+    }
+
     button {
       background: none;
       border: none;
@@ -86,11 +120,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 +176,26 @@ export class VolumeControl extends LitElement {
   // LIFECYCLE
   // ===================================================================
 
+  override connectedCallback() {
+    super.connectedCallback();
+
+    this.unsubscribeStyle = volumeStyleStore.subscribe(() => {
+      this.popup = volumeStyleStore.popup;
+      this.setAvailable(volumeStyleStore.available);
+
+      // 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();
+    });
+
+    this.setAvailable(volumeStyleStore.available);
+
+    void volumeStyleStore.init();
+  }
+
   override disconnectedCallback() {
     super.disconnectedCallback();
+    this.unsubscribeStyle?.();
     document.removeEventListener('click', this.boundHandleOutsideClick);
     clearTimeout(this.volumeDebounceTimer);
   }
@@ -154,10 +226,12 @@ export class VolumeControl extends LitElement {
   private handleOutsideClick(e: Event) {
     const path = e.composedPath();
 
-    if (!path.includes(this)) {
+    if (!path.includes(this)) this.closeSlider();
-      this.showSlider = false;
+  }
-      document.removeEventListener('click', this.boundHandleOutsideClick);
+
-    }
+  private closeSlider() {
+    this.showSlider = false;
+    document.removeEventListener('click', this.boundHandleOutsideClick);
   }
 
   private handleInput(e: Event) {
@@ -189,21 +263,67 @@ export class VolumeControl extends LitElement {
   // RENDER
   // ===================================================================
 
+  /**
+   * `hidden` is set imperatively rather than reflected from the state,
+   * because it has to be on the *host* and a `@state` does not reflect.
+   * It is the right attribute besides: it takes the element out of the
+   * accessibility tree as well as out of the layout.
+   */
+  private setAvailable(available: boolean) {
+    this.available = available;
+    this.hidden = !available;
+
+    // A popup left open when the control goes away would keep its
+    // document click listener installed for markup that no longer
+    // renders.
+    if (!available) this.closeSlider();
+  }
+
   override render() {
+    if (!this.available) return nothing;
+
     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;
@@ -3207,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

@@ -7,6 +7,8 @@ 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';
 
@@ -114,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.
@@ -167,12 +196,9 @@ export class BottomNav extends LitElement {
         nameDialog(this.drawer);
     }
 
-    private onGlobalNavigate = (e: Event) => {
+    private onGlobalNavigate = () => {
-        const detail = (e as CustomEvent<{ view?: string }>).detail;
-
-        if (detail?.view) this.activeView = detail.view;
-
         // 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;
     };
 
@@ -202,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)}

frontend/src/components/config-page/config-page.ts

@@ -9,7 +9,13 @@ import {
     RemoveLibrary,
     GetRemovalImpact,
     GetAllLibrariesWithTrackCounts,
+    ScanLibrary,
+    ScanAllLibraries,
+    FullRescan,
 } from '@go/library/library.js';
+import { jobStore } from '@store/job-store';
+import type { Job } from '@store/job-store';
+import '@components/jobs/job-panel';
 import {
     GetScanConcurrency,
     SetScanConcurrency,
@@ -19,6 +25,8 @@ import {
     SetQueueFallback,
     GetAllowMeteredCatalogDownload,
     SetAllowMeteredCatalogDownload,
+    GetPopupVolume,
+    SetPopupVolume,
 } from '@go/config/config.js';
 import { GetIndexStatus } from '@go/explore/service.js';
 import { notificationStore } from '@store/notification-store';
@@ -27,6 +35,9 @@ import type * as library from '@go/library/models.js';
 import { ThemeController } from '@store/controllers/theme-controller';
 import { TrackListController } from '@store/controllers/tracklist-controller';
 import { FavoritesController } from '@store/controllers/favorites-controller';
+import { ViewVisibilityController } from '@store/controllers/view-visibility-controller';
+import { VIEW_META } from '../../services/view-meta';
+import { downloadStore } from '@store/download-store';
 import { GetAllPlaylists } from '@go/playlist/service.js';
 import type * as playlist from '@go/playlist/models.js';
 import { Events } from '../../events';
@@ -45,6 +56,10 @@ import {
 
 import './config-field';
 import './config-section';
+// The view filter's home (#148). The same component the top bar
+// carries, placed a second time rather than reimplemented -- two
+// definitions of "which library am I browsing" is what this is for.
+import '@components/library-filter/library-filter';
 import './download-clients';
 import './shortcut-capture';
 import { confirmAction } from '../confirm-dialog/confirm-dialog';
@@ -71,6 +86,27 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
     // --- Favorites controller ---
     private favCtrl = new FavoritesController(this);
 
+    /** Which destinations the navigation offers (#25). */
+    private viewsCtrl = new ViewVisibilityController(this);
+
+    /**
+     * The job snapshot, for the per-library scan status (#27).
+     *
+     * Held as state rather than read from the store in `render()` so
+     * Lit sees the dependency: the store notifies, and a getter read
+     * inside a template is not a reactive input.
+     */
+    @state() private jobs: Job[] = [];
+
+    /**
+     * Set between pressing a scan button and the job snapshot that
+     * proves it started -- `JobsChanged` is coalesced at 250 ms, which
+     * is long enough for a second click to start a second scan.
+     */
+    @state() private startingScan = false;
+
+    private unsubscribeJobs: (() => void) | null = null;
+
     // --- Shortcuts controller ---
     private shortcutsCtrl = new ShortcutsController(this);
 
@@ -95,6 +131,8 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
     @state() private concurrencyMode = 'auto';
     @state() private defaultPage = 'home';
     @state() private queueFallback = 'favorites';
+
+    @state() private popupVolume = false;
     @state() private indexStatus: explore.IndexStatus | null = null;
     /** Three states, not one: the panel used to say "Loading status…"
      *  for the entire session, because the only thing that ever set
@@ -197,6 +235,42 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
             flex-wrap: wrap;
         }
 
+        /* #148, and the second half of #57.
+
+           library-filter is the only control in the app that calls
+           setSelectedLibrary, and it lived in the top bar -- which
+           #57 takes out of the layout on a phone, and which #143
+           already refused to hide as a fit step precisely because
+           hiding it takes away an action. So the selection gets a home
+           that does not depend on that bar existing.
+
+           At every width, not below 600px: a phone-only copy would be
+           a second place the control lives, and "where do I change
+           which library I am browsing" having two answers by size is
+           the fault, not the fix. */
+        .library-scope {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            gap: 1em;
+            flex-wrap: wrap;
+            margin-bottom: 1em;
+        }
+
+        .library-scope .scope-label {
+            font-weight: 600;
+            font-size: 0.85em;
+            color: var(--yj-text-primary, #fff);
+            display: block;
+        }
+
+        .library-scope .scope-description {
+            font-size: 0.75em;
+            color: var(--yj-text-tertiary, #888);
+            margin: 0.35em 0 0;
+            max-width: 40em;
+        }
+
         .save-row {
             display: flex;
             gap: 0.5em;
@@ -469,6 +543,12 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
             flex: 1;
         }
 
+        .view-note {
+            color: var(--yj-text-tertiary, #888);
+            font-size: var(--yj-font-size-sm, 0.85rem);
+            margin-left: auto;
+        }
+
         .column-arrows {
             display: flex;
             gap: 0.15em;
@@ -852,8 +932,14 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
         this.scrollMode =
             localStorage.getItem(SCROLL_STORAGE_KEY) || 'hover';
 
-        // Scan progress lives in the jobs panel now — this page only
+        // Scanning is started and watched here (#27), so the job
-        // needs to know when the library list itself changes.
+        // snapshot is a live input to this page.
+        this.unsubscribeJobs = jobStore.subscribe(() => {
+            this.jobs = jobStore.jobs;
+        });
+        this.jobs = jobStore.jobs;
+        void jobStore.init();
+
         this.cancelLibraryAdded = EventsOn(
             Events.LibraryAdded,
             () => void this.loadLibraries(),
@@ -884,6 +970,9 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
     }
 
     protected override onViewDeactivate(): void {
+        this.unsubscribeJobs?.();
+        this.unsubscribeJobs = null;
+
         this.cancelLibraryAdded?.();
         this.cancelLibraryRenamed?.();
         this.cancelLibraryRemoved?.();
@@ -893,20 +982,28 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
 
     private async loadLibraries(): Promise<void> {
         try {
-            const [libs, mode, defaultPage, queueFallback, allowMetered] =
+            const [
-                await Promise.all([
+                libs,
-                    GetAllLibrariesWithTrackCounts(),
+                mode,
-                    GetScanConcurrency(),
+                defaultPage,
-                    GetDefaultPage(),
+                queueFallback,
-                    GetQueueFallback(),
+                allowMetered,
-                    GetAllowMeteredCatalogDownload(),
+                popupVolume,
-                ]);
+            ] = await Promise.all([
+                GetAllLibrariesWithTrackCounts(),
+                GetScanConcurrency(),
+                GetDefaultPage(),
+                GetQueueFallback(),
+                GetAllowMeteredCatalogDownload(),
+                GetPopupVolume(),
+            ]);
 
             this.libraries = libs ?? [];
             this.concurrencyMode = mode;
             this.defaultPage = defaultPage;
             this.queueFallback = queueFallback;
             this.allowMeteredCatalogDownload = allowMetered;
+            this.popupVolume = popupVolume;
 
         } catch (err) {
             console.error(
@@ -1084,6 +1181,133 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
         }
     }
 
+    // ===================================================================
+    // SCANNING (#27 — back from the Jobs tab)
+    // ===================================================================
+
+    /** The scan job for a library, if one is registered. */
+    private jobForLibrary(id: number): Job | undefined {
+        return this.jobs.find((job) => job.id === `scan:${id}`);
+    }
+
+    /** The status line under a library name while it is being scanned. */
+    private libraryScanStatus(id: number): string | null {
+        const job = this.jobForLibrary(id);
+
+        if (!job) return null;
+
+        switch (job.state) {
+            case 'running':
+                return job.phase ? `Scanning · ${job.phase}` : 'Scanning';
+            case 'queued':
+                return 'Queued';
+            case 'paused':
+                return 'Paused';
+            case 'pausing':
+                return 'Pausing…';
+            case 'cancelling':
+                return 'Stopping…';
+            default:
+                return null;
+        }
+    }
+
+    private get anyScanning(): boolean {
+        return this.libraries.some(
+            (lib) => this.libraryScanStatus(lib.id) !== null,
+        );
+    }
+
+    /**
+     * Run something that starts a job, holding the buttons until the
+     * snapshot lands and saying so when it does not start at all.
+     *
+     * Persistent, not a toast: the user asked for work to happen, it
+     * did not, and retrying is exactly the useful response.
+     */
+    private async startJob(
+        what: string,
+        start: () => Promise<unknown>,
+        retry: () => void,
+    ): Promise<void> {
+        if (this.startingScan) return;
+
+        this.startingScan = true;
+
+        try {
+            await start();
+        } catch (err) {
+            console.error(`${what} failed:`, err);
+            notificationStore.persistent({
+                key: 'scan-start',
+                title: 'Scan did not start',
+                text: `${what} failed. ${describeError(err)}`,
+                detail: String(err),
+                action: { label: 'Try again', run: retry },
+            });
+        } finally {
+            this.startingScan = false;
+        }
+    }
+
+    private handleScanLibrary = (id: number): void => {
+        this.activeMenuId = null;
+        void this.startJob(
+            'Scanning that library',
+            () => ScanLibrary(id),
+            () => this.handleScanLibrary(id),
+        );
+    };
+
+    private handleScanAll = (): void => {
+        void this.startJob(
+            'Scanning your libraries',
+            () => ScanAllLibraries(),
+            () => this.handleScanAll(),
+        );
+    };
+
+    private handleFullRescan = async (): Promise<void> => {
+        const ok = await confirmAction({
+            title: 'Full rescan',
+            message:
+                'This deletes all library data — including downloaded '
+                + 'cover art — and rebuilds it from your files.',
+            impact:
+                'It is not the same as “Scan now”, which only picks up '
+                + 'what changed.',
+            confirmLabel: 'Rebuild everything',
+            danger: true,
+        });
+
+        if (!ok) return;
+
+        await this.startJob(
+            'The full rescan',
+            () => FullRescan(),
+            () => void this.handleFullRescan(),
+        );
+    };
+
+    private handleViewToggle = (
+        view: string,
+        visible: boolean,
+    ): void => {
+        this.viewsCtrl
+            .setVisible(view, visible)
+            .catch((err: unknown) => {
+                console.error('Failed to save view visibility:', err);
+                notificationStore.transient({
+                    key: 'view-visibility',
+                    text: `Could not change which views are shown. ${describeError(err)}`,
+                    detail: String(err),
+                });
+                // The checkbox has already flipped itself; the store is
+                // the truth, so redraw from it.
+                this.requestUpdate();
+            });
+    };
+
     private handleDefaultPageChange = (
         e: CustomEvent<ConfigFieldChangeEvent>,
     ): void => {
@@ -1428,6 +1652,7 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
             -->
             ${this.renderLibrarySection()}
             ${this.renderGeneralSection()}
+            ${this.renderNavigationSection()}
             ${this.renderNowPlayingSection()}
             ${this.renderThemeSection()}
             ${this.renderTrackListSection()}
@@ -1522,6 +1747,20 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                     .value=${this.allowMeteredCatalogDownload}
                     @config-change=${this.handleAllowMeteredChange}
                 ></config-field>
+
+                <!--
+                  The tier list above says what the build is *doing*;
+                  this says it is a job, and gives it the pause, cancel
+                  and log the tier list never had (#27). Cancelling one
+                  still asks first — that confirmation is inside
+                  applyJobControl, keyed on the kind, which is why
+                  this embeds the shared rows rather than drawing its
+                  own.
+                -->
+                <job-panel
+                    kinds="index-build,catalog-enrich"
+                    heading="Index jobs"
+                ></job-panel>
             </config-section>
         `;
     }
@@ -1642,18 +1881,15 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                         description:
                             'The page the app opens to on launch.',
                         type: 'select' as const,
-                        options: [
+                        // Derived, not written out: this list was a
-                            { value: 'home', label: 'Home' },
+                        // second copy of the launchable set, and #27
-                            { value: 'tracks', label: 'Tracks' },
+                        // removing a destination is exactly the change
-                            { value: 'albums', label: 'Albums' },
+                        // that would have left the two disagreeing.
-                            { value: 'artists', label: 'Artists' },
+                        // Settings is excluded because it is the one
-                            { value: 'genres', label: 'Genres' },
+                        // view the backend refuses to launch into.
-                            { value: 'playlists', label: 'Playlists' },
+                        options: VIEW_META
-                            { value: 'explore', label: 'Explore' },
+                            .filter((v) => v.alwaysShown !== true)
-                            { value: 'downloads', label: 'Downloads' },
+                            .map((v) => ({ value: v.id, label: v.label })),
-                            { value: 'autotag', label: 'Autotag' },
-                            { value: 'jobs', label: 'Jobs' },
-                        ],
                     }}
                     .value=${this.defaultPage}
                     @config-change=${this.handleDefaultPageChange}
@@ -1674,6 +1910,120 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                     .value=${this.queueFallback}
                     @config-change=${this.handleQueueFallbackChange}
                 ></config-field>
+                <config-field
+                    .schema=${{
+                        key: 'popupVolume',
+                        label: 'Volume opens in a popup',
+                        description:
+                            'Off, the volume slider is always visible in the '
+                            + 'player bar. On, it hides behind the speaker '
+                            + 'icon. The slider stands down on a phone either '
+                            + 'way, where the hardware keys own volume.',
+                        type: 'toggle' as const,
+                    }}
+                    .value=${this.popupVolume}
+                    @config-change=${this.handlePopupVolumeChange}
+                ></config-field>
+            </config-section>
+        `;
+    }
+
+    /**
+     * The volume control's presentation (#42).
+     *
+     * In General rather than beside the theme because it is about the
+     * transport's behaviour rather than its colours, and next to "When
+     * the Queue Ends" because both are answers to "how should the
+     * player behave".
+     */
+    private handlePopupVolumeChange = (
+        e: CustomEvent<ConfigFieldChangeEvent>,
+    ): void => {
+        const popup = Boolean(e.detail.value);
+        const previous = this.popupVolume;
+
+        this.popupVolume = popup;
+
+        void SetPopupVolume(popup).catch((err: unknown) => {
+            console.error('failed to save the volume control setting', err);
+            this.popupVolume = previous;
+            notificationStore.transient({
+                key: 'popup-volume-setting',
+                title: 'Setting not saved',
+                text: describeError(err, 'That setting could not be saved.'),
+            });
+        });
+    };
+
+    // --- Navigation section ---
+
+    /**
+     * Which destinations the sidebar and the phone's tab bar offer.
+     *
+     * Two items are drawn but not editable, and both say why in place
+     * rather than being silently inert. Settings is never hideable --
+     * the backend refuses it too, because `config.toml` is
+     * hand-editable. The launch page is not hideable *while it is the
+     * launch page*, which is a state the user can leave by changing the
+     * launch page above; refusing is preferable to the alternatives,
+     * since resetting their launch page silently changes a second thing
+     * they chose and allowing it lands the app on a page nothing points
+     * at.
+     */
+    private renderNavigationSection() {
+        return html`
+            <config-section
+                heading="Navigation"
+                description="Choose which destinations the sidebar and the phone's tab bar offer. Hiding one does not remove it — links and the launch page still open it."
+            >
+                <ul class="column-list">
+                    ${repeat(VIEW_META, (v) => v.id, (v) => {
+            const checked = this.viewsCtrl.enabled(v.id);
+            const isLaunchPage = this.defaultPage === v.id;
+            const locked = v.alwaysShown === true || isLaunchPage;
+
+            let note = '';
+
+            if (v.alwaysShown === true) {
+                note = 'Always shown.';
+            } else if (isLaunchPage) {
+                note = 'This is the launch page.';
+            } else if (
+                v.id === 'downloads' &&
+                checked &&
+                !downloadStore.available
+            ) {
+                // The config says show it and the nav does not, which
+                // would otherwise read as the checkbox not working.
+                note = 'Hidden until a download client is configured.';
+            }
+
+            return html`
+                            <li
+                                class="column-item ${checked ? 'enabled' : 'disabled'}"
+                            >
+                                <input
+                                    type="checkbox"
+                                    class="column-toggle"
+                                    aria-label="Show ${v.label} in the navigation"
+                                    .checked=${checked}
+                                    ?disabled=${locked}
+                                    @change=${(e: Event) =>
+                    this.handleViewToggle(
+                        v.id,
+                        (e.target as HTMLInputElement).checked,
+                    )}
+                                />
+                                <span class="column-label">
+                                    ${v.label}
+                                </span>
+                                ${note
+                    ? html`<span class="view-note">${note}</span>`
+                    : nothing}
+                            </li>
+                        `;
+        })}
+                </ul>
             </config-section>
         `;
     }
@@ -2056,10 +2406,25 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
         return html`
             <config-section
                 heading="Libraries"
-                description="Manage your music library folders. Scanning and its
+                description="Manage your music library folders, and scan them
-                    progress live in the Jobs panel."
+                    for new and changed files."
                 .open=${true}
             >
+                <div class="library-scope">
+                    <div>
+                        <span class="scope-label">Showing</span>
+                        <p class="scope-description">
+                            Which library the Albums, Artists and Genres
+                            views show. This is a view filter, not a
+                            setting about the libraries themselves — the
+                            list below is where they are added, renamed
+                            and scanned.
+                        </p>
+                    </div>
+                    <library-filter data-testid="settings-library-filter">
+                    </library-filter>
+                </div>
+
                 <div class="scan-actions">
                     <button
                         class="btn-primary"
@@ -2067,6 +2432,23 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                     >
                         Add Library
                     </button>
+                    <button
+                        ?disabled=${this.anyScanning
+                || this.startingScan
+                || this.libraries.length === 0}
+                        @click=${this.handleScanAll}
+                    >
+                        Scan All
+                    </button>
+                    <button
+                        class="btn-danger"
+                        ?disabled=${this.anyScanning
+                || this.startingScan
+                || this.libraries.length === 0}
+                        @click=${this.handleFullRescan}
+                    >
+                        Full Rescan
+                    </button>
                 </div>
 
                 ${this.libraries.length > 0
@@ -2104,7 +2486,8 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                                         <span class="library-count">
                                             ${this.removingLibraryId === lib.id
                                                 ? 'Removing…'
-                                                : html`${lib.trackCount} tracks`}
+                                                : this.libraryScanStatus(lib.id)
+                                                    ?? html`${lib.trackCount} tracks`}
                                         </span>
                                         <div class="overflow-wrapper">
                                             <button
@@ -2127,6 +2510,16 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                                                           >
                                                               Rename
                                                           </div>
+                                                          ${this.libraryScanStatus(lib.id) === null
+                                                            ? html`
+                                                                  <div
+                                                                      class="overflow-item"
+                                                                      @click=${() => this.handleScanLibrary(lib.id)}
+                                                                  >
+                                                                      Scan now
+                                                                  </div>
+                                                              `
+                                                            : nothing}
                                                           <div
                                                               class="overflow-item overflow-item--danger"
                                                               @click=${() => void this.handleRemoveClick(lib.id)}
@@ -2170,6 +2563,11 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
                     @config-change=${this.handleConcurrencyChange}
                 ></config-field>
 
+                <job-panel
+                    kinds="library-scan"
+                    heading="Scans"
+                ></job-panel>
+
             </config-section>
         `;
     }

frontend/src/components/config-page/download-clients.ts

@@ -22,6 +22,7 @@ import { compact } from '@utils/binding';
 import { describeError, explainError } from '@utils/describe-error';
 import { confirmAction } from '@components/confirm-dialog/confirm-dialog';
 import './config-section';
+import '@components/jobs/job-panel';
 import { pickDirectory } from '../../utils/pick-directory';
 
 /**
@@ -274,6 +275,17 @@ export class DownloadClients extends LitElement {
                             </wa-button>
                         </div>
                     `}
+
+                <!--
+                  The Downloads view already shows every download's
+                  lifecycle state; what it has never had is pause,
+                  cancel and the log, which the Jobs tab carried (#27).
+                  Renders nothing while nothing is downloading.
+                -->
+                <job-panel
+                    kinds="download"
+                    heading="Downloads in progress"
+                ></job-panel>
             </config-section>
 
             <config-section

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

@@ -23,7 +23,8 @@ import { gridColumnsFor, gridSpacingFor } from '@utils/grid-spacing';
 import { queueStore } from '@store/queue-store';
 import type { QueueSource } from '@store/queue-store';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@components/playlist-picker/playlist-picker.js';
@@ -51,7 +52,7 @@ import {
     ContextMenuController,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { creditLink, exploreLinkStyles } from '../../utils/explore-link';
 import { creditStore } from '@store/credit-store';
@@ -415,17 +416,17 @@ export class CoverGrid
     splitIndex = 0;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     // ContextMenuHost interface.
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -2087,11 +2088,8 @@ export class CoverGrid
         const { ctxMenu } = this;
 
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${ctxMenu.contextMenuOpen}
             >
                 ${ctxMenu.contextMenuOpen
@@ -2204,13 +2202,12 @@ export class CoverGrid
                           </div>
                       `
                 : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${ctxMenu.playlistSubmenuOpen}
             >
                 ${ctxMenu.playlistSubmenuOpen
@@ -2232,7 +2229,7 @@ export class CoverGrid
                           </div>
                       `
                 : nothing}
-            </wa-popup>
+            </menu-surface>
 
             <track-details></track-details>
         `;

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

@@ -246,7 +246,7 @@ export class DownloadPicker extends LitElement {
             return html`
                 <wa-callout variant="success">
                     Found a clear match and started downloading it. Progress is
-                    in the background jobs panel.
+                    on the Downloads page.
                 </wa-callout>
             `;
         }

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

@@ -3,6 +3,7 @@ import { customElement, state } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@components/page-header/page-header';
+import type { PageAction } from '@components/page-header/page-header';
 import { designTokens } from '../../styles/tokens.css';
 import { downloadStore, stateLabel } from '@store/download-store';
 import type { Request, RequestSummary, DownloadView as DownloadRecord } from '@store/download-store';
@@ -246,23 +247,23 @@ export class DownloadsView extends ViewLifecycleMixin(LitElement) {
 
     override render() {
         return html`
-            <page-header heading="Downloads">
+            <page-header
-                ${this.tab === 'requests'
+                heading="Downloads"
-                    ? html`
+                .actions=${this.tab === 'requests'
-                          <wa-button
+                    ? ([
-                              slot="actions"
+                          {
-                              size="small"
+                              id: 'check-now',
-                              appearance="outlined"
+                              label: this.checking
-                              ?disabled=${this.checking}
+                                  ? 'Searching\u2026'
-                              title="Search every download client for everything on this list right now, instead of waiting for the next scheduled check"
+                                  : 'Check now',
-                              @click=${() => void this.checkNow()}
+                              icon: 'rotate',
-                          >
+                              disabled: this.checking,
-                              <wa-icon slot="start" name="rotate"></wa-icon>
+                              title: 'Search every download client for everything on this list right now, instead of waiting for the next scheduled check',
-                              ${this.checking ? 'Searching…' : 'Check now'}
+                              onSelect: () => void this.checkNow(),
-                          </wa-button>
+                          },
-                      `
+                      ] satisfies PageAction[])
-                    : nothing}
+                    : []}
-            </page-header>
+            ></page-header>
 
             <p class="subtitle">
                 Music you have requested, and the download attempts that

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

@@ -49,9 +49,11 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
 import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import { dictByName } from '@utils/binding';
 import type { TrackDetails } from '@components/track-details/track-details.js';
@@ -327,7 +329,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
     @state() private ctxMenuTrack: MBTrack | null = null;
 
     @query('#track-context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
     private playlistSubmenuPopup?: WaPopup;
@@ -337,11 +339,11 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
     // -- ContextMenuHost interface --
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -3781,11 +3783,8 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         const track = this.ctxMenuTrack;
 
         return html`
-            <wa-popup
+            <menu-surface
                 id="track-context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu.contextMenuOpen}
             >
                 ${this.ctxMenu.contextMenuOpen && track
@@ -3846,13 +3845,12 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu.playlistSubmenuOpen}
             >
                 ${this.ctxMenu.playlistSubmenuOpen
@@ -3869,7 +3867,7 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 }

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

@@ -61,9 +61,11 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
 import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import { dict, dictByName } from '@utils/binding';
 import type { TrackDetails } from '@components/track-details/track-details.js';
@@ -215,7 +217,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
     @state() private ctxMenuTarget: ContextMenuTarget | null = null;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
     private playlistSubmenuPopup?: WaPopup;
@@ -233,11 +235,11 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
 
     // -- ContextMenuHost interface --
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -2621,11 +2623,8 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
         const target = this.ctxMenuTarget;
 
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu.contextMenuOpen}
             >
                 ${this.ctxMenu.contextMenuOpen && target
@@ -2643,13 +2642,12 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu.playlistSubmenuOpen}
             >
                 ${this.ctxMenu.playlistSubmenuOpen
@@ -2666,7 +2664,7 @@ export class ExploreArtistDetails extends LitElement implements ContextMenuHost
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 

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

@@ -37,9 +37,11 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
 import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import { dict, dictByName } from '@utils/binding';
 import { ICON_QUEUE } from '@utils/icon-language';
@@ -206,13 +208,13 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
     @state() private ctxMenuTarget: ExploreMenuTarget | null = null;
 
     @litQuery('#explore-context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     // -- ContextMenuHost interface --
     // No playlist submenu — same reason as the album/artist detail
     // pages: every action here resolves its one file lazily.
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
@@ -1341,11 +1343,8 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
         const owned = Boolean(target?.localId);
 
         return html`
-            <wa-popup
+            <menu-surface
                 id="explore-context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu.contextMenuOpen}
             >
                 ${this.ctxMenu.contextMenuOpen && target
@@ -1374,7 +1373,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) implements Conte
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 

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

@@ -24,14 +24,15 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
 import { RovingGridController } from '@utils/roving-grid';
 
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@components/playlist-picker/playlist-picker.js';
 import { dictByName } from '@utils/binding';
@@ -137,19 +138,19 @@ export class GenresView
     private contextMenuGenreName: string | null = null;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     // ----- ContextMenuHost interface -----
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
     getPlaylistSubmenuPopup():
-        | WaPopup
+        | MenuTarget
         | undefined {
         return this.playlistSubmenuPopup;
     }
@@ -1176,11 +1177,8 @@ export class GenresView
 
     private renderContextMenu() {
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .contextMenuOpen}
             >
@@ -1284,13 +1282,12 @@ export class GenresView
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .playlistSubmenuOpen}
             >
@@ -1318,7 +1315,7 @@ export class GenresView
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 

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

@@ -1,8 +1,9 @@
 import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
-import '@awesome.me/webawesome/dist/components/button/button.js';
 import { GetShelves } from '@go/home/service.js';
+import { ICON_SHUFFLE } from '@utils/icon-language';
+import type { PageAction } from '@components/page-header/page-header';
 import { GetAlbumTracks } from '@go/library/library.js';
 import type * as home from '@go/home/models.js';
 import type * as library from '@go/library/models.js';
@@ -160,29 +161,52 @@ export class HomeView extends ViewLifecycleMixin(LitElement) {
                 user-select: none;
             }
 
+            /*
+             * The hover play button is a *hover* affordance, so it is
+             * gated on the device having hover rather than on width.  A
+             * touch long-press synthesises a hover state in the WebView,
+             * so on a phone it flashed into view during the 500ms hold
+             * that utils/long-press.ts is measuring for a context menu —
+             * a control appearing because you were reaching for a
+             * different one.  A phone user taps the album and plays from
+             * the detail view, so there is nothing to replace it with.
+             *
+             * display:none outside the query rather than opacity:0 on
+             * its own: an opacity-0 button still takes taps and is
+             * still in the accessibility tree, so the invisible control
+             * would keep the hit area it was never meant to have on
+             * touch. Everything else stays inside, so the desktop
+             * animation is unchanged.
+             */
             .play {
-                position: absolute;
+                display: none;
-                right: 8px;
-                bottom: 8px;
-                width: 38px;
-                height: 38px;
-                border: none;
-                border-radius: 50%;
-                background: var(--yj-accent, #ffd43b);
-                color: var(--yj-accent-fg, #000);
-                display: flex;
-                align-items: center;
-                justify-content: center;
-                cursor: pointer;
-                opacity: 0;
-                transform: translateY(6px);
-                transition: opacity 0.12s ease, transform 0.12s ease;
             }
 
-            .card:hover .play,
+            @media (hover: hover) and (pointer: fine) {
-            .card:focus-within .play {
+                .play {
-                opacity: 1;
+                    position: absolute;
-                transform: translateY(0);
+                    right: 8px;
+                    bottom: 8px;
+                    width: 38px;
+                    height: 38px;
+                    border: none;
+                    border-radius: 50%;
+                    background: var(--yj-accent, #ffd43b);
+                    color: var(--yj-accent-fg, #000);
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    cursor: pointer;
+                    opacity: 0;
+                    transform: translateY(6px);
+                    transition: opacity 0.12s ease, transform 0.12s ease;
+                }
+
+                .card:hover .play,
+                .card:focus-within .play {
+                    opacity: 1;
+                    transform: translateY(0);
+                }
             }
 
             .name {
@@ -260,23 +284,24 @@ export class HomeView extends ViewLifecycleMixin(LitElement) {
 
     override render() {
         return html`
-            <page-header heading="Home">
+            <page-header
-                <!-- "Shuffle" alone was two different controls with one
+                heading="Home"
-                     name: this one and the transport's shuffle mode.
+                .actions=${[
-                     They were never on screen together until the app
+                    {
-                     started landing on Home (H-8), and a cached view is
+                        // "Shuffle" alone was two different controls
-                     in the accessibility tree either way. -->
+                        // with one name: this one and the transport's
-                <wa-button
+                        // shuffle mode. They were never on screen
-                    slot="actions"
+                        // together until the app started landing on
-                    size="small"
+                        // Home (H-8), and a cached view is in the
-                    appearance="plain"
+                        // accessibility tree either way.
-                    title="Reshuffle the suggestions"
+                        id: 'shuffle-suggestions',
-                    @click=${() => void this.load()}
+                        label: 'Shuffle suggestions',
-                >
+                        icon: ICON_SHUFFLE,
-                    <wa-icon slot="start" name="shuffle"></wa-icon>
+                        title: 'Reshuffle the suggestions',
-                    Shuffle suggestions
+                        onSelect: () => void this.load(),
-                </wa-button>
+                    },
-            </page-header>
+                ] satisfies PageAction[]}
+            ></page-header>
             <p class="lede">Somewhere to start listening.</p>
             ${this.renderBody()}
         `;

frontend/src/components/jobs/job-band.ts

@@ -0,0 +1,132 @@
+/**
+ * The phone's view of background work (#62).
+ *
+ * The header `job-indicator` is a *popover*, anchored to a bar 3.25em
+ * tall on a screen 439 CSS px tall, and it was reported as unreadable
+ * behind other UI. Two things are wrong with it there regardless of
+ * that symptom: a popover is a **disclosure**, and background work is
+ * the one thing a phone should not make you open something to see; and
+ * #57 deletes the bar it is anchored to, and is blocked on this issue
+ * precisely because the indicator needs somewhere else to live first.
+ *
+ * This is that somewhere. Below 600px the indicator stands down
+ * (`index.css`) and its work appears here instead.
+ *
+ * Four things about it are load-bearing.
+ *
+ * **It is the existing `job-panel`, not a second job UI.** Pause,
+ * cancel, Details and the log all come along — and, more to the point,
+ * so does `applyJobControl`, which is what carries the "you will
+ * discard hours of downloading" confirmation for an index build. A
+ * host drawing its own buttons drops that silently, which is the trap
+ * #27 already named.
+ *
+ * **It is in the layout, not over it**, and that was measured rather
+ * than assumed. The first version of this put the panel in
+ * `notification-host`'s fixed band, which 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 e2e specs failed —
+ * two phone-shell journeys and the header's action menu — because the
+ * panel was intercepting the taps. A band that hides the app to tell
+ * you the app is busy is worse than the popover it replaced. In flow
+ * it pushes instead, so nothing is covered and nothing is unreachable,
+ * which is #24's one sentence across all three bands.
+ *
+ * **It shows active work only.** A finished row that lingers is a
+ * banner that stays after the work is done, which is the opposite of
+ * what #62 asks for ("dismissed automatically on completion") and, in
+ * flow, is furniture that keeps the content pushed down. Finished jobs
+ * are still shown where the work was started, which is #27's rule and
+ * unaffected.
+ *
+ * **It renders nothing at all above 600px**, from `matchMedia` rather
+ * than a media query, because this decides whether the element
+ * *exists*. `bottom-nav` learned that the expensive way: rendering its
+ * duplicate `<app-sidebar>` unconditionally put a second copy of every
+ * `nav-*` testid in the DOM and broke 30 specs on a viewport where it
+ * was not even visible. Settings already holds four `job-panel`s, so a
+ * fifth answering for *every* kind is the same trap.
+ */
+import { LitElement, html, css, nothing } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+
+import { jobStore } from '@store/job-store';
+import { isTerminal } from '@store/job-store';
+import { designTokens } from '../../styles/tokens.css';
+import { PHONE_QUERY } from '../../utils/breakpoints';
+import './job-panel';
+
+@customElement('job-band')
+export class JobBand extends LitElement {
+    @state() private phone = false;
+
+    @state() private active = 0;
+
+    private media?: MediaQueryList;
+
+    private unsubscribe?: () => void;
+
+    static override styles = [
+        designTokens,
+        css`
+            :host {
+                display: block;
+                min-width: 0;
+            }
+
+            /* The panel's own margin is for a settings section; here the
+               band owns the spacing. */
+            job-panel {
+                margin-top: 0;
+                padding: 0 0.5em 0.5em;
+            }
+        `,
+    ];
+
+    private onMedia = (e: MediaQueryListEvent | MediaQueryList) => {
+        this.phone = e.matches;
+    };
+
+    private onJobs = () => {
+        this.active = jobStore.jobs.filter((job) => !isTerminal(job)).length;
+    };
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+
+        this.media = window.matchMedia(PHONE_QUERY);
+        this.phone = this.media.matches;
+        this.media.addEventListener('change', this.onMedia);
+
+        // The band decides whether to render *at all*, and a panel that
+        // hides itself cannot tell its host that.
+        this.unsubscribe = jobStore.subscribe(this.onJobs);
+        this.onJobs();
+        void jobStore.init();
+    }
+
+    override disconnectedCallback(): void {
+        super.disconnectedCallback();
+        this.unsubscribe?.();
+        this.media?.removeEventListener('change', this.onMedia);
+    }
+
+    override render() {
+        // `hidden` rather than an empty render, so the grid row this
+        // sits in costs nothing at all while there is no work -- the
+        // rule `job-panel` already follows one layer down.
+        this.hidden = !(this.phone && this.active > 0);
+
+        if (this.hidden) return nothing;
+
+        return html`
+            <job-panel kinds="*" density="compact" active-only></job-panel>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'job-band': JobBand;
+    }
+}

frontend/src/components/jobs/job-indicator.ts

@@ -155,13 +155,27 @@ export class JobIndicator extends LitElement {
                goes -- the live region in render() is what announces
                this, and it is unaffected, so the ring keeps its
                accessible name and screen readers keep hearing the
-               state change. */
+               state change.
+
+               [compact] is the same removal asked for by measurement
+               rather than by width, and it is set from outside: the
+               shell's fit pass (services/top-bar-fit.ts, #143) owns
+               it, because between 600 and 900 whether this label fits
+               depends on what else is in the bar and on how long the
+               running job's title is -- 235px for "Scanning Music from
+               the external drive" -- rather than on the viewport. Two
+               triggers, one effect, and the phone's is unconditional
+               because it was argued and pinned before this existed. */
             @media (max-width: 599px) {
                 .label {
                     display: none;
                 }
             }
 
+            :host([compact]) .label {
+                display: none;
+            }
+
             .alert-dot {
                 width: 6px;
                 height: 6px;

frontend/src/components/jobs/job-panel.ts

@@ -0,0 +1,267 @@
+import { LitElement, html, css, nothing } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { designTokens } from '../../styles/tokens.css';
+import { jobStore } from '@store/job-store';
+import type { Job, JobKind } from '@store/job-store';
+import { isTerminal } from '@store/job-store';
+import './job-row';
+import './job-details-drawer';
+import { applyJobControl } from './job-controls';
+import { jobStateStyles } from './job-format';
+
+/**
+ * The background work of one kind, rendered wherever that work is
+ * started or configured.
+ *
+ * #27 folded the Jobs tab away, and the shape it folded into is this
+ * rather than one "Background jobs" panel in Settings — which would
+ * have been the tab again under another name. Reading the app first
+ * turned up that **four of the five job kinds already had a home**
+ * showing their work: Settings → Search Index draws per-tier index
+ * progress, `downloads-view` draws every download's lifecycle state,
+ * `autotag-view` draws its own apply ring, and only `library-scan` had
+ * nowhere but the tab. What none of those four had is the *generic*
+ * affordances — pause, cancel, "Details", the log, and a finished job
+ * you can dismiss — which is what this carries to each of them.
+ *
+ * Three things about it are load-bearing.
+ *
+ * **The controls are `applyJobControl`, not a reimplementation.** That
+ * is what keeps the "you will discard hours of downloading"
+ * confirmation on an index build alive across the move: it is keyed on
+ * `KindIndexBuild` inside the shared handler, and a host that rendered
+ * its own buttons would silently drop it.
+ *
+ * **A panel with nothing to say renders nothing at all**, host padding
+ * included — an idle panel in four places is four pieces of furniture
+ * describing an absence. That is the rule `startBackfillJob` follows
+ * for the indicator, one layer up.
+ *
+ * **There is no "Clear finished" here**, because `ClearFinishedJobs` is
+ * global: a Clear in the Libraries panel would silently discard the
+ * index build's history too. A finished row dismisses itself, which is
+ * per-job and is what `job-row` already offers.
+ */
+@customElement('job-panel')
+export class JobPanel extends LitElement {
+    /**
+     * Comma-separated job kinds, e.g. `index-build,catalog-enrich`.
+     *
+     * An attribute rather than a property because every call site is a
+     * literal in a template, and one of them is inside an HTMX-adjacent
+     * settings page where a property binding would be one more thing to
+     * remember.
+     *
+     * **`*` means every kind**, which is the phone's band (#62) and
+     * nothing else: there, this panel is standing in for the header
+     * indicator, whose whole job was to be the one view of everything
+     * at once. It is spelled `*` rather than taken as the meaning of an
+     * empty attribute, because empty is what a typo and a missing
+     * binding both produce and "show everything" is the wrong thing to
+     * do by accident. Empty still shows nothing.
+     */
+    @property({ type: String })
+    kinds = '';
+
+    /** Heading above the rows. Omitted renders no heading. */
+    @property({ type: String })
+    heading = '';
+
+    /**
+     * Row density, passed to `job-row`.
+     *
+     * `full` adds elapsed time and per-job statistics and is what a
+     * settings section wants, so it stays the default and the four
+     * existing call sites are unchanged. `compact` is what `job-row`
+     * itself calls "the popover density", and it is what the phone's
+     * band uses (#62) — there this panel *is* the popover, on a screen
+     * 439 CSS px tall, and the full density spent 259 of them.
+     */
+    @property({ type: String })
+    density: 'compact' | 'full' = 'full';
+
+    /**
+     * Drop finished rows.
+     *
+     * For the phone's band (#62), which is *in the layout*: a finished
+     * row there is a banner that stays after the work is done and keeps
+     * the content pushed down. Settings keeps them, because that is
+     * where "did the last scan work" is asked, and a finished row there
+     * dismisses itself.
+     */
+    @property({ type: Boolean, attribute: 'active-only' })
+    activeOnly = false;
+
+    @state()
+    private jobs: Job[] = [];
+
+    @state()
+    private drawerJobId = '';
+
+    @state()
+    private drawerOpen = false;
+
+    private unsubscribe: (() => void) | null = null;
+
+    static override styles = [
+        designTokens,
+        jobStateStyles,
+        css`
+            :host {
+                display: block;
+                margin-top: 1em;
+            }
+
+            /* An empty panel takes no room at all, margin included. */
+            :host([hidden]) {
+                display: none;
+            }
+
+            h3 {
+                font-size: var(--yj-text-sm);
+                text-transform: uppercase;
+                letter-spacing: 0.06em;
+                color: var(--yj-text-tertiary, #868e96);
+                margin: 0 0 0.5em;
+            }
+
+            .card {
+                background: var(--yj-bg-surface, #2b3035);
+                border: 1px solid var(--yj-border, #495057);
+                border-radius: 6px;
+                overflow: hidden;
+            }
+
+            .job-entry {
+                display: flex;
+                align-items: center;
+                gap: 0.75em;
+                padding: 0.6em 0.8em;
+                border-bottom: 1px solid var(--yj-border-subtle, #3a4046);
+            }
+
+            .job-entry:last-child {
+                border-bottom: none;
+            }
+
+            job-row {
+                flex: 1;
+                /* A grid child's implicit minimum is its content, and a
+                   job title is long. */
+                min-width: 0;
+            }
+
+            .details-btn {
+                background: none;
+                border: 1px solid var(--yj-border, #495057);
+                border-radius: 4px;
+                color: var(--yj-text-secondary, #adb5bd);
+                cursor: pointer;
+                font-family: inherit;
+                font-size: var(--yj-text-sm);
+                padding: 0.3em 0.6em;
+                white-space: nowrap;
+            }
+
+            .details-btn:hover {
+                color: var(--yj-text-primary, #e9ecef);
+            }
+        `,
+    ];
+
+    override connectedCallback() {
+        super.connectedCallback();
+        this.unsubscribe = jobStore.subscribe(() => {
+            this.jobs = jobStore.jobs;
+        });
+        this.jobs = jobStore.jobs;
+        void jobStore.init();
+    }
+
+    override disconnectedCallback() {
+        super.disconnectedCallback();
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+    }
+
+    /** The kinds this panel answers for. */
+    private get wanted(): ReadonlySet<string> {
+        return new Set(
+            this.kinds
+                .split(',')
+                .map((k) => k.trim())
+                .filter(Boolean),
+        );
+    }
+
+    private get mine(): Job[] {
+        const ofKind =
+            this.kinds.trim() === '*'
+                ? this.jobs
+                : this.jobs.filter((job) =>
+                      this.wanted.has(job.kind as JobKind),
+                  );
+
+        return this.activeOnly ? ofKind.filter((job) => !isTerminal(job)) : ofKind;
+    }
+
+    private openDetails(id: string) {
+        this.drawerJobId = id;
+        this.drawerOpen = true;
+    }
+
+    private onDrawerClosed = () => {
+        this.drawerOpen = false;
+    };
+
+    override render() {
+        const mine = this.mine;
+
+        // Hidden rather than empty: see the class comment. The drawer
+        // goes with it, since it can only have been opened from a row.
+        this.hidden = mine.length === 0;
+
+        if (mine.length === 0) return nothing;
+
+        const active = mine.filter((job) => !isTerminal(job));
+        const finished = mine.filter(isTerminal);
+
+        return html`
+            ${this.heading ? html`<h3>${this.heading}</h3>` : nothing}
+            <div class="card">
+                ${[...active, ...finished].map(
+                    (job) => html`
+                        <div class="job-entry">
+                            <job-row
+                                .job=${job}
+                                variant=${this.density}
+                                @job-control=${applyJobControl}
+                            ></job-row>
+                            <button
+                                type="button"
+                                class="details-btn"
+                                @click=${() => this.openDetails(job.id)}
+                            >
+                                Details${job.warnCount
+                                    ? ` · ${job.warnCount}⚠`
+                                    : ''}
+                            </button>
+                        </div>
+                    `,
+                )}
+            </div>
+
+            <job-details-drawer
+                job-id=${this.drawerJobId}
+                ?open=${this.drawerOpen}
+                @drawer-closed=${this.onDrawerClosed}
+            ></job-details-drawer>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'job-panel': JobPanel;
+    }
+}

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

@@ -1,568 +0,0 @@
-import { LitElement, html, css, nothing } from 'lit';
-import { customElement, state } from 'lit/decorators.js';
-import '@awesome.me/webawesome/dist/components/icon/icon.js';
-import '@components/page-header/page-header';
-import { designTokens } from '../../styles/tokens.css';
-import {
-    GetAllLibrariesWithTrackCounts,
-    ScanLibrary,
-    ScanAllLibraries,
-    FullRescan,
-} from '@go/library/library.js';
-import type * as library from '@go/library/models.js';
-import { EventsOn } from '@runtime/runtime';
-import { Events } from '../../events';
-import { jobStore } from '@store/job-store';
-import type { Job } from '@store/job-store';
-import { notificationStore } from '@store/notification-store';
-import { describeError } from '@utils/describe-error';
-import { confirmAction } from '../confirm-dialog/confirm-dialog';
-import './job-row';
-import './job-details-drawer';
-import { applyJobControl } from './job-controls';
-import { jobStateStyles } from './job-format';
-import { ViewLifecycleMixin } from '../../utils/view-lifecycle';
-
-type LibraryInfo = library.Info;
-
-/** Job states meaning the job will not progress further. */
-const TERMINAL_STATES: ReadonlySet<string> = new Set([
-    'complete',
-    'cancelled',
-    'error',
-]);
-
-/**
- * Full-page view of background work: everything running right now, the
- * per-library scan controls that used to live in Settings, and a short
- * history of what recently finished.
- *
- * This is the same job rows as the top-bar popover at a larger density —
- * one implementation, two placements, so the two can never disagree.
- */
-@customElement('jobs-view')
-export class JobsView extends ViewLifecycleMixin(LitElement) {
-    @state()
-    private jobs: Job[] = [];
-
-    @state()
-    private libraries: LibraryInfo[] = [];
-
-    @state()
-    private drawerJobId = '';
-
-    @state()
-    private drawerOpen = false;
-
-    /**
-     * Set between pressing a scan button and the job snapshot that
-     * proves it started. `anyScanning` is derived from `JobsChanged`,
-     * which is coalesced at 250 ms — long enough for a second click to
-     * start a second scan (errors.M5).
-     */
-    @state()
-    private starting = false;
-
-    private unsubscribe: (() => void) | null = null;
-
-    private eventCleanups: Array<() => void> = [];
-
-    static override styles = [
-        designTokens,
-        jobStateStyles,
-        css`
-            :host {
-                display: block;
-                overflow-y: auto;
-                height: 100%;
-                padding: 1.5em 1.75em 3em;
-                box-sizing: border-box;
-            }
-
-            /* The header supplies its own padding and rule, so it runs
-               to the edge of a host that pads its own content. */
-            page-header {
-                margin: -1.5em -1.75em 1em;
-            }
-
-            h1 {
-                font-size: var(--yj-text-xl);
-                color: var(--yj-text-primary, #e9ecef);
-                margin: 0 0 0.2em;
-            }
-
-            .page-sub {
-                font-size: var(--yj-text-md);
-                color: var(--yj-text-tertiary, #868e96);
-                margin: 0 0 1.75em;
-            }
-
-            section {
-                margin-bottom: 2em;
-            }
-
-            .section-head {
-                display: flex;
-                align-items: center;
-                justify-content: space-between;
-                gap: 1em;
-                margin-bottom: 0.75em;
-            }
-
-            h2 {
-                font-size: var(--yj-text-sm);
-                text-transform: uppercase;
-                letter-spacing: 0.06em;
-                color: var(--yj-text-tertiary, #868e96);
-                margin: 0;
-            }
-
-            .card {
-                background: rgba(255, 255, 255, 0.03);
-                border: 1px solid rgba(255, 255, 255, 0.07);
-                border-radius: 10px;
-                overflow: hidden;
-            }
-
-            .card > * + * {
-                border-top: 1px solid rgba(255, 255, 255, 0.06);
-            }
-
-            .job-entry {
-                display: grid;
-                grid-template-columns: 1fr auto;
-                align-items: center;
-                gap: 0.5em;
-                padding-right: 0.75em;
-            }
-
-            .empty {
-                padding: 1.1em;
-                font-size: var(--yj-text-md);
-                color: var(--yj-text-tertiary, #868e96);
-                font-style: italic;
-            }
-
-            .library-row {
-                display: grid;
-                grid-template-columns: 1fr auto;
-                align-items: center;
-                gap: 1em;
-                padding: 0.75em 0.9em;
-            }
-
-            .library-name {
-                font-size: var(--yj-text-md);
-                color: var(--yj-text-primary, #e9ecef);
-            }
-
-            .library-meta {
-                font-size: var(--yj-text-sm);
-                color: var(--yj-text-tertiary, #868e96);
-                margin-top: 0.15em;
-                overflow-wrap: anywhere;
-            }
-
-            .library-state {
-                font-size: var(--yj-text-sm);
-                color: var(--job-tone);
-                margin-top: 0.15em;
-            }
-
-            button.action {
-                display: inline-flex;
-                align-items: center;
-                gap: 0.45em;
-                border: 1px solid rgba(255, 255, 255, 0.14);
-                border-radius: 7px;
-                background: rgba(255, 255, 255, 0.05);
-                color: var(--yj-text-primary, #e9ecef);
-                font-size: var(--yj-text-sm);
-                padding: 0.42em 0.85em;
-                cursor: pointer;
-                white-space: nowrap;
-                transition:
-                    background-color 120ms ease,
-                    border-color 120ms ease;
-            }
-
-            button.action:hover:not(:disabled) {
-                background: rgba(255, 255, 255, 0.11);
-            }
-
-            button.action:disabled {
-                opacity: 0.4;
-                cursor: default;
-            }
-
-            button.action:focus-visible {
-                outline: 2px solid var(--yj-accent, #ffd43b);
-                outline-offset: 2px;
-            }
-
-            button.action.danger {
-                color: var(--yj-error-text, #ff8787);
-                border-color: rgba(255, 107, 107, 0.35);
-            }
-
-            button.action.danger:hover:not(:disabled) {
-                background: rgba(255, 107, 107, 0.12);
-            }
-
-            button.link {
-                border: none;
-                background: transparent;
-                color: var(--yj-accent-text, #ffd43b);
-                font-size: var(--yj-text-sm);
-                cursor: pointer;
-                padding: 0.2em 0.4em;
-                border-radius: 5px;
-            }
-
-            button.link:hover {
-                text-decoration: underline;
-            }
-
-            .details-btn {
-                border: none;
-                background: transparent;
-                color: var(--yj-text-secondary, #adb5bd);
-                font-size: var(--yj-text-sm);
-                cursor: pointer;
-                padding: 0.3em 0.5em;
-                border-radius: 6px;
-                white-space: nowrap;
-            }
-
-            .details-btn:hover {
-                background: rgba(255, 255, 255, 0.1);
-                color: var(--yj-text-primary, #e9ecef);
-            }
-        `,
-    ];
-
-    protected override onViewActivate(): void {
-        this.unsubscribe = jobStore.subscribe(() => {
-            this.jobs = jobStore.jobs;
-        });
-        void jobStore.init();
-        this.jobs = jobStore.jobs;
-        void this.loadLibraries();
-
-        // Library CRUD happens elsewhere; keep the picker in step.
-        for (const event of [
-            Events.LibraryAdded,
-            Events.LibraryRemoved,
-            Events.LibraryRenamed,
-            Events.LibraryScanComplete,
-        ]) {
-            this.eventCleanups.push(
-                EventsOn(event, () => void this.loadLibraries()),
-            );
-        }
-    }
-
-    protected override onViewDeactivate(): void {
-        this.unsubscribe?.();
-        this.unsubscribe = null;
-        this.eventCleanups.forEach((off) => off());
-        this.eventCleanups = [];
-    }
-
-    private async loadLibraries(): Promise<void> {
-        try {
-            this.libraries = (await GetAllLibrariesWithTrackCounts()) ?? [];
-        } catch (err) {
-            console.error('Failed to load libraries:', err);
-        }
-    }
-
-    /** The scan job for a library, if one is registered. */
-    private jobForLibrary(id: number): Job | undefined {
-        return jobStore.getJob(`scan:${id}`);
-    }
-
-    private openDetails(id: string) {
-        this.drawerJobId = id;
-        this.drawerOpen = true;
-    }
-
-    private onDrawerClosed = () => {
-        this.drawerOpen = false;
-    };
-
-    /**
-     * Run something that starts a job, holding the buttons until the
-     * snapshot lands and saying so when it does not start at all.
-     *
-     * Persistent, not a toast: the user asked for work to happen, it
-     * did not, and retrying is exactly the useful response.
-     */
-    private async startJob(
-        what: string,
-        start: () => Promise<unknown>,
-        retry: () => void,
-    ): Promise<void> {
-        if (this.starting) return;
-
-        this.starting = true;
-
-        try {
-            await start();
-        } catch (err) {
-            console.error(`${what} failed:`, err);
-            notificationStore.persistent({
-                key: 'scan-start',
-                title: 'Scan did not start',
-                text: `${what} failed. ${describeError(err)}`,
-                detail: String(err),
-                action: { label: 'Try again', run: retry },
-            });
-        } finally {
-            this.starting = false;
-        }
-    }
-
-    private async startScan(id: number) {
-        await this.startJob(
-            'Scanning that library',
-            () => ScanLibrary(id),
-            () => void this.startScan(id),
-        );
-    }
-
-    private async startAllScans() {
-        await this.startJob(
-            'Scanning your libraries',
-            () => ScanAllLibraries(),
-            () => void this.startAllScans(),
-        );
-    }
-
-    private async clearFinished() {
-        await jobStore.clearFinished();
-    }
-
-    private async fullRescan() {
-        const ok = await confirmAction({
-            title: 'Full rescan',
-            message:
-                'This deletes all library data — including downloaded ' +
-                'cover art — and rebuilds it from your files.',
-            impact:
-                'It is not the same as “Scan now”, which only picks up ' +
-                'what changed.',
-            confirmLabel: 'Rebuild everything',
-            danger: true,
-        });
-
-        if (!ok) return;
-
-        await this.startJob(
-            'The full rescan',
-            () => FullRescan(),
-            () => void this.fullRescan(),
-        );
-    }
-
-    private renderJobList(list: Job[], emptyText: string) {
-        if (list.length === 0) {
-            return html`<div class="card">
-                <div class="empty">${emptyText}</div>
-            </div>`;
-        }
-
-        return html`
-            <div class="card">
-                ${list.map(
-                    (job) => html`
-                        <div class="job-entry">
-                            <job-row
-                                .job=${job}
-                                variant="full"
-                                @job-control=${applyJobControl}
-                            ></job-row>
-                            <button
-                                class="details-btn"
-                                @click=${() => this.openDetails(job.id)}
-                            >
-                                Details${job.warnCount
-                                    ? ` · ${job.warnCount}⚠`
-                                    : ''}
-                            </button>
-                        </div>
-                    `,
-                )}
-            </div>
-        `;
-    }
-
-    /** The status line under a library name in the scan-control list. */
-    private libraryStatus(job: Job | undefined): string | null {
-        if (!job) return null;
-
-        switch (job.state) {
-            case 'running':
-                return job.phase ? `Scanning · ${job.phase}` : 'Scanning';
-            case 'queued':
-                return 'Queued';
-            case 'paused':
-                return 'Paused';
-            case 'pausing':
-                return 'Pausing…';
-            case 'cancelling':
-                return 'Stopping…';
-            default:
-                return null;
-        }
-    }
-
-    private renderLibraryRow(lib: LibraryInfo) {
-        const job = this.jobForLibrary(lib.id);
-        const status = this.libraryStatus(job);
-        const busy = status !== null;
-
-        return html`
-            <div class="library-row">
-                <div>
-                    <div class="library-name">${lib.name}</div>
-                    <div class="library-meta">
-                        ${lib.trackCount.toLocaleString()} tracks · ${lib.path}
-                    </div>
-                    ${status
-                        ? html`<div class="library-state">${status}</div>`
-                        : nothing}
-                </div>
-
-                ${busy
-                    ? html`
-                          <button
-                              class="link"
-                              @click=${() => this.openDetails(`scan:${lib.id}`)}
-                          >
-                              View progress
-                          </button>
-                      `
-                    : html`
-                          <button
-                              class="action"
-                              ?disabled=${this.starting}
-                              @click=${() => this.startScan(lib.id)}
-                          >
-                              <wa-icon name="arrows-rotate"></wa-icon>
-                              Scan now
-                          </button>
-                      `}
-            </div>
-        `;
-    }
-
-    override render() {
-        // Derived from `this.jobs` rather than the store getters so Lit
-        // sees the reactive dependency and re-renders on every snapshot.
-        const active = this.jobs.filter((j) => !TERMINAL_STATES.has(j.state));
-        const finished = this.jobs.filter((j) => TERMINAL_STATES.has(j.state));
-        const anyScanning = this.libraries.some((lib) =>
-            Boolean(this.libraryStatus(this.jobForLibrary(lib.id))),
-        );
-
-        return html`
-            <page-header heading="Background jobs"></page-header>
-            <p class="page-sub">
-                Library scans and search index builds, with their progress and
-                output.
-            </p>
-
-            <section>
-                <div class="section-head">
-                    <h2>Running now</h2>
-                </div>
-                ${this.renderJobList(active, 'Nothing is running.')}
-            </section>
-
-            <section>
-                <div class="section-head">
-                    <h2>Libraries</h2>
-                    <button
-                        class="action"
-                        ?disabled=${anyScanning ||
-                        this.starting ||
-                        this.libraries.length === 0}
-                        @click=${this.startAllScans}
-                    >
-                        <wa-icon name="arrows-rotate"></wa-icon>
-                        Scan all
-                    </button>
-                </div>
-
-                <div class="card">
-                    ${this.libraries.length === 0
-                        ? html`<div class="empty">
-                              No libraries yet — add one in Settings.
-                          </div>`
-                        : this.libraries.map((lib) =>
-                              this.renderLibraryRow(lib),
-                          )}
-                </div>
-            </section>
-
-            <section>
-                <div class="section-head">
-                    <h2>Maintenance</h2>
-                </div>
-                <div class="card">
-                    <div class="library-row">
-                        <div>
-                            <div class="library-name">Full rescan</div>
-                            <div class="library-meta">
-                                Wipes all library data and cover art, then
-                                rebuilds from your files. Only needed when the
-                                library is corrupt — a normal scan already
-                                picks up changes.
-                            </div>
-                        </div>
-                        <button
-                            class="action danger"
-                            ?disabled=${anyScanning ||
-                            this.starting ||
-                            this.libraries.length === 0}
-                            @click=${this.fullRescan}
-                        >
-                            <wa-icon name="triangle-exclamation"></wa-icon>
-                            Full rescan
-                        </button>
-                    </div>
-                </div>
-            </section>
-
-            ${finished.length > 0
-                ? html`
-                      <section>
-                          <div class="section-head">
-                              <h2>Recently finished</h2>
-                              <button
-                                  class="link"
-                                  @click=${this.clearFinished}
-                              >
-                                  Clear
-                              </button>
-                          </div>
-                          ${this.renderJobList(finished, '')}
-                      </section>
-                  `
-                : nothing}
-
-            <job-details-drawer
-                job-id=${this.drawerJobId}
-                ?open=${this.drawerOpen}
-                @drawer-closed=${this.onDrawerClosed}
-            ></job-details-drawer>
-        `;
-    }
-}
-
-declare global {
-    interface HTMLElementTagNameMap {
-        'jobs-view': JobsView;
-    }
-}

frontend/src/components/menu-surface/menu-surface.ts

@@ -0,0 +1,318 @@
+/**
+ * Where a context menu is drawn: a popup on a desktop, a bottom sheet
+ * on a phone (#60).
+ *
+ * Every context menu in this app is a `.context-menu-panel` inside a
+ * `<wa-popup>` anchored to the touch point, driven by
+ * `ContextMenuController`. On the reference device that is structurally
+ * broken, and the failure was measured on the hardware rather than
+ * inferred:
+ *
+ * - Chrome 113 has **no Popover API** (`popover` is Chrome 114), so
+ *   `wa-popup` takes its own documented fallback and positions with
+ *   `strategy: "fixed"` instead of the top layer. Measured on the
+ *   device: `HTMLElement.prototype.hasOwnProperty('popover')` is false
+ *   and the popup's computed `position` is `fixed`.
+ * - `index.css` puts `contain: layout style paint` on `.main-panel`,
+ *   the ancestor of every view. Paint containment **clips** fixed
+ *   descendants. Measured: `.main-panel` computes `contain: content`
+ *   and spans 0-318 of a 439px viewport, while the open menu spans
+ *   191-401 — so 83px of it, three of its seven items, is cut off.
+ *
+ * A `<dialog>` fixes it by construction rather than by styling, because
+ * `showModal()` is Chrome 37 and uses the real top layer. **That was
+ * measured too, and it needed to be**: every other dialog in this app
+ * is mounted in `index.html`, *outside* `.main-panel`, so "dialogs are
+ * fine" was not evidence about a dialog opened from inside a view. A
+ * probe dialog appended to `track-list`'s shadow root paints to y=439,
+ * over the mini player and the tab bar, with the contained ancestor
+ * still there.
+ *
+ * Four things about this component are load-bearing.
+ *
+ * **It is one element with two presentations, not two components.**
+ * The host keeps rendering exactly the panel it rendered before and
+ * slots it into whichever surface is up, so the twelve call sites
+ * changed one tag name each and nothing else — no second item model, no
+ * second keyboard model, and `ContextMenuController` still drives
+ * `.active` and `.anchor` as if it were talking to a `wa-popup`.
+ *
+ * **Which surface exists is `matchMedia`, not a media query.** The
+ * decision is whether a `<dialog>` is in the tree at all, which is
+ * `job-band` and `player-controls`' rule: a `display: none` surface is
+ * still in the shadow root and still something a positional or by-role
+ * query finds.
+ *
+ * **The sheet has to un-do the UA stylesheet to be full-bleed.**
+ * A native `<dialog>` carries `max-width: calc(100% - 6px - 2em)` and
+ * `margin: auto`, which on the device produced a 354px panel floating
+ * in the middle of a 424px screen. `max-width: none` and explicit
+ * margins are what make it a sheet rather than a small centred box.
+ * The *positioning* needs no such care: a top-layer dialog's containing
+ * block is the viewport even with a paint-contained ancestor, which is
+ * why `bottom: 0` reaches y=439 and not the main panel's 318.
+ *
+ * **Dismissal has to travel back.** `wa-dialog` closes itself on
+ * Escape, which would otherwise leave the controller's
+ * `contextMenuOpen` true and the menu unopenable until something else
+ * cleared it. `menu-dismiss` is that signal, and the controller listens
+ * for it on the document beside the click and contextmenu listeners it
+ * already has.
+ */
+import { LitElement, css, html } from 'lit';
+import { customElement, property, query, state } from 'lit/decorators.js';
+import '@awesome.me/webawesome/dist/components/popup/popup.js';
+import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
+import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+
+import { PHONE_QUERY } from '@utils/breakpoints';
+import { nameDialogsIn } from '@utils/name-dialog';
+
+/** The event a surface dispatches when it closed itself. */
+export const MENU_DISMISS_EVENT = 'menu-dismiss';
+
+/**
+ * The event a surface dispatches once it has finished showing.
+ *
+ * Only the sheet sends it, and only because `wa-dialog` moves focus to
+ * itself on the frame after `showModal()` -- see `MenuKeyboard.refocus`
+ * for why waiting longer is not the fix.
+ */
+export const MENU_SHOWN_EVENT = 'menu-shown';
+
+/**
+ * A `wa-popup` anchor: a real element or a virtual one.
+ *
+ * `undefined` rather than `null` for "not set yet", because that is
+ * what `wa-popup`'s own property accepts — this surface hands the value
+ * straight through and must not widen it.
+ */
+type MenuAnchor = WaPopup['anchor'] | undefined;
+
+/** A `wa-dialog`, as much of it as this file needs. */
+type DialogEl = HTMLElement & { open: boolean };
+
+@customElement('menu-surface')
+export class MenuSurface extends LitElement {
+    /** Whether the menu is showing. Set by `ContextMenuController`. */
+    @property({ type: Boolean }) active = false;
+
+    /**
+     * Where the popup hangs from. Ignored in sheet mode, which is
+     * anchored to the bottom of the screen rather than to the touch
+     * point — that is the whole point of a sheet.
+     */
+    @property({ attribute: false }) anchor: MenuAnchor = undefined;
+
+    /**
+     * `wa-popup`'s placement, defaulted because all twelve call sites
+     * passed the same one. Kept as a property so a future menu that
+     * wants another does not have to reach past this component.
+     */
+    @property() placement = 'bottom-start';
+
+    /**
+     * What to call the sheet, for a surface whose content is not a
+     * `.context-menu-panel` with an `aria-label` of its own -- the
+     * playlist submenu, whose content is a `playlist-picker`.
+     */
+    @property() label = '';
+
+    @state() private sheet = false;
+
+    @query('wa-popup') private popup?: WaPopup;
+
+    @query('wa-dialog') private dialog?: DialogEl;
+
+    private phoneQuery?: MediaQueryList;
+
+    static override styles = css`
+        :host {
+            display: contents;
+        }
+
+        wa-popup {
+            z-index: 200;
+        }
+
+        /* The sheet. A native dialog's UA stylesheet centres it and
+           caps its width, which on the device drew a 354px box in the
+           middle of a 424px screen — so all four of these are undoing
+           that rather than decorating. */
+        wa-dialog::part(dialog) {
+            margin: auto auto 0 auto;
+            max-width: none;
+            max-height: 85vh;
+            width: 100%;
+            border-radius: 12px 12px 0 0;
+            background: var(--yj-bg-elevated, #343a40);
+            padding: 0;
+        }
+
+        /* **A long menu scrolls; it does not hang off the bottom.**
+           Measured on the device at 80vh: seven 48px rows plus the grip
+           came to 364px against a 351px dialog, so the last row's
+           bottom was at y=452 on a 439px screen -- the one row a
+           destructive action is most likely to be. The cap has to stay
+           (a sheet covering the whole screen is a page, not a sheet),
+           so the body is what gives. */
+        wa-dialog::part(body) {
+            padding: 0;
+            overflow-y: auto;
+        }
+
+        /* A sheet is dragged at with a thumb, so it says where its top
+           edge is. Decorative: the panel below it carries the actions. */
+        .grip {
+            width: 36px;
+            height: 4px;
+            margin: 8px auto 4px;
+            border-radius: 2px;
+            background: var(--yj-text-tertiary, #888);
+        }
+    `;
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+
+        // Looked up here rather than at module load, so a test can
+        // install its own matchMedia before the element is created.
+        this.phoneQuery = window.matchMedia?.(PHONE_QUERY);
+        this.sheet = this.phoneQuery?.matches ?? false;
+        this.phoneQuery?.addEventListener('change', this.onPhoneChange);
+    }
+
+    override disconnectedCallback(): void {
+        super.disconnectedCallback();
+        this.phoneQuery?.removeEventListener('change', this.onPhoneChange);
+    }
+
+    private onPhoneChange = (e: MediaQueryListEvent): void => {
+        this.sheet = e.matches;
+    };
+
+    /**
+     * Re-run the popup's positioning.
+     *
+     * Forwarded rather than dropped because `page-header` calls it when
+     * it opens the overflow menu: the popup is rendered before the
+     * button it anchors to has settled. A sheet has nothing to
+     * reposition -- it is anchored to the bottom of the screen -- so
+     * there it is deliberately a no-op rather than an error.
+     */
+    reposition(): void {
+        this.popup?.reposition();
+    }
+
+    /**
+     * The panel the host slotted in. It is light DOM here and stays in
+     * the host's shadow root, which is what keeps the host's own
+     * `contextMenuStyles` applying to it in both presentations.
+     */
+    private get panel(): HTMLElement | null {
+        return this.querySelector('.context-menu-panel');
+    }
+
+    override updated(): void {
+        const panel = this.panel;
+
+        // The sheet's rows are bigger, and that rule lives in the one
+        // stylesheet every call site already includes rather than in
+        // twelve places. The attribute is how it knows.
+        if (panel) panel.toggleAttribute('data-sheet', this.sheet);
+
+        if (this.sheet) {
+            this.syncSheet(panel);
+
+            return;
+        }
+
+        if (this.popup) {
+            if (this.anchor) this.popup.anchor = this.anchor;
+
+            this.popup.active = this.active;
+        }
+    }
+
+    private syncSheet(panel: HTMLElement | null): void {
+        const dialog = this.dialog;
+
+        if (!dialog) return;
+
+        // The dialog is named after the menu it contains, so no call
+        // site has to say the same thing twice: the panel already
+        // carries `role="menu"` and an `aria-label` naming what it acts
+        // on. `without-header` renders no heading, which is
+        // `name-dialog`'s documented `aria-label` path.
+        const label = panel?.getAttribute('aria-label') || this.label;
+
+        if (label) dialog.setAttribute('label', label);
+
+        nameDialogsIn(this.shadowRoot);
+
+        if (dialog.open !== this.active) dialog.open = this.active;
+    }
+
+    /**
+     * `wa-dialog` closed itself — Escape, or its own close button.
+     * The controller owns `contextMenuOpen`, so it has to hear about
+     * it or the menu is left open in state and shut on screen.
+     */
+    private onDialogShown = (): void => {
+        if (!this.active) return;
+
+        this.dispatchEvent(
+            new CustomEvent(MENU_SHOWN_EVENT, {
+                bubbles: true,
+                composed: true,
+            }),
+        );
+    };
+
+    private onDialogHide = (): void => {
+        if (!this.active) return;
+
+        this.dispatchEvent(
+            new CustomEvent(MENU_DISMISS_EVENT, {
+                bubbles: true,
+                composed: true,
+            }),
+        );
+    };
+
+    override render() {
+        if (this.sheet) {
+            // **The anchor stays out of the sheet.** One call site --
+            // `page-header`'s overflow menu -- slots its own trigger
+            // button as the thing the popup hangs from, and a sheet
+            // hangs from the bottom of the screen instead. Rendering
+            // that slot outside the dialog is what keeps the button on
+            // the page rather than inside the surface it opens.
+            return html`
+                <slot name="anchor"></slot>
+                <wa-dialog
+                    without-header
+                    data-testid="menu-sheet"
+                    @wa-after-show=${this.onDialogShown}
+                    @wa-hide=${this.onDialogHide}
+                >
+                    <div class="grip"></div>
+                    <slot></slot>
+                </wa-dialog>
+            `;
+        }
+
+        return html`
+            <wa-popup placement=${this.placement} flip shift>
+                <slot name="anchor" slot="anchor"></slot>
+                <slot></slot>
+            </wa-popup>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'menu-surface': MenuSurface;
+    }
+}

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

@@ -0,0 +1,133 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import '@awesome.me/webawesome/dist/components/icon/icon.js';
+import { designTokens } from '../../styles/tokens.css';
+import { HistoryController } from '@store/controllers/history-controller';
+
+/**
+ * Global back and forward, in the top bar (#6).
+ *
+ * **The stack was already global; the affordance was not.** Every
+ * navigation has been a history entry since the Android back gesture
+ * landed, and `popstate` restores any of them in either direction --
+ * `back-navigation.spec.ts` has asserted `goForward()` since it was
+ * written. What the report describes as "back is tab-scoped" is that
+ * the *only* way back was a detail view's own button, which vanishes
+ * the moment you leave for another tab: the album you were reading is
+ * still one entry away, and nothing on screen says so or offers it.
+ *
+ * Four things about this are load-bearing.
+ *
+ * **It asks the shell rather than the History API.** `history.length`
+ * counts entries this app did not push and never shrinks, and there is
+ * no way to ask where in the list you are -- so a control derived from
+ * it is confidently wrong at both ends. `historyStore` is the shell's
+ * own numbering.
+ *
+ * **A control that cannot act is `disabled`, not hidden.** This is the
+ * one place in the app where that is right rather than the fault
+ * `library-status-indicator` was: back and forward are a *pair* whose
+ * positions the user learns, and a button that disappears at the end
+ * of the list moves the other one under the cursor. It is also what
+ * every browser does, which is the whole design brief here.
+ *
+ * **The buttons dispatch the events the rest of the app already
+ * dispatches**, `navigate-back` and `navigate-forward`, rather than
+ * calling `history.back()` themselves. The shell owns the guard -- one
+ * press is one entry, and at the root there is nothing of ours to go
+ * back to -- and a second caller reaching for `history` directly is
+ * how the old `navStack` came to disagree with the platform.
+ *
+ * **It is desktop chrome.** Below 600px the phone has a system back
+ * gesture (and, on Android, a hardware/gesture Back that this app
+ * hooks), the top bar is 3.25em with three other things in it, and two
+ * more 32px targets there would be the first thing to overflow. Hidden
+ * by `index.css` at that width, next to the rest of the phone header's
+ * concessions.
+ */
+@customElement('nav-history')
+export class NavHistory extends LitElement {
+    private historyCtrl = new HistoryController(this);
+
+    static override styles = [designTokens, css`
+        :host {
+            display: flex;
+            align-items: center;
+            gap: 0.25em;
+            /* A grid item's implicit minimum is its content; this one
+               genuinely cannot shrink, so it says so rather than
+               letting the header widen the body. */
+            flex: 0 0 auto;
+        }
+
+        button {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            width: 2em;
+            height: 2em;
+            padding: 0;
+            border: none;
+            border-radius: 50%;
+            background: transparent;
+            color: var(--yj-text-primary, #f8f9fa);
+            cursor: pointer;
+            font-size: 1em;
+        }
+
+        button:hover:not(:disabled) {
+            background-color: var(--yj-bg-overlay, #495057);
+        }
+
+        button:focus-visible {
+            outline: 2px solid var(--yj-accent, #ffd43b);
+            outline-offset: 2px;
+        }
+
+        button:disabled {
+            /* Not a contrast failure: a disabled control is exempt from
+               1.4.3, and the pair has to read as unavailable rather
+               than merely quiet. */
+            color: var(--yj-text-tertiary, #868e96);
+            cursor: default;
+        }
+    `];
+
+    private go(direction: 'back' | 'forward') {
+        this.dispatchEvent(new CustomEvent(`navigate-${direction}`, {
+            bubbles: true,
+            composed: true,
+        }));
+    }
+
+    override render() {
+        const { canBack, canForward } = this.historyCtrl.depth;
+
+        return html`
+            <button
+                type="button"
+                data-testid="history-back"
+                aria-label="Back"
+                ?disabled=${!canBack}
+                @click=${() => this.go('back')}
+            >
+                <wa-icon name="arrow-left"></wa-icon>
+            </button>
+            <button
+                type="button"
+                data-testid="history-forward"
+                aria-label="Forward"
+                ?disabled=${!canForward}
+                @click=${() => this.go('forward')}
+            >
+                <wa-icon name="arrow-right"></wa-icon>
+            </button>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'nav-history': NavHistory;
+    }
+}

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

@@ -15,6 +15,7 @@ import { FavoritesController } from '@store/controllers/favorites-controller';
 import { designTokens } from '../../styles/tokens.css';
 import { srOnly } from '../../styles/sr-only.css';
 import { ICON_QUEUE } from '@utils/icon-language';
+import { openQueue as showQueue } from '@utils/open-queue';
 
 /**
  * What is playing, at the size a phone has room for (plan 016 B2,
@@ -116,8 +117,27 @@ export class NowPlayingView extends LitElement {
         .art .placeholder {
             /* Square, and never taller than the room left over: the
                art is the one thing here that would happily push the
-               transport off the bottom of a short phone. */
+               transport off the bottom of a short phone.
+
+               **max-height is what actually keeps that promise**, and
+               it was missing. With a definite width and
+               a 1:1 aspect-ratio the height is *derived from the width*
+               and is bounded by nothing: at the reference device's
+               424x439 that is a 263px square (60vh) in a box with far
+               less than 263px left, so the art overflowed its own
+               centred flex item and drew over the header above and the
+               title below it. The comment claimed this was handled;
+               60vh is a bound on the *viewport*, not on the room left
+               over, and those differ by however much chrome is above
+               and below.
+
+               Pre-existing -- screenshotted on main -- and made acute
+               by #56, which gives the transport 95px more than it had.
+               Found by reading a screenshot, which is the only tier
+               that can see it: nothing fails, nothing overflows the
+               *shell*, and every control is still hittable. */
             width: min(100%, 60vh);
+            max-height: 100%;
             aspect-ratio: 1;
             object-fit: cover;
             border-radius: 12px;
@@ -226,13 +246,15 @@ export class NowPlayingView extends LitElement {
      *
      * This view hides the bottom bar (index.css), and the bar is where
      * the queue button lives -- so without this, going full-screen
-     * would take the queue away. It toggles the same `open` attribute
+     * would take the queue away. It goes through the same helper
      * `index.ts` does, because the panel's state is an attribute on one
      * element and a second mechanism for it is a second thing to keep
-     * in step.
+     * in step -- which is exactly what this button was: it set `open`
+     * directly, so on a phone it produced a queue with no history entry
+     * behind it and back moved the page underneath instead (#55).
      */
     private openQueue() {
-        document.getElementById('queue-panel')?.setAttribute('open', '');
+        showQueue();
     }
 
     private toggleFavorite() {
@@ -314,7 +336,19 @@ export class NowPlayingView extends LitElement {
 
             <div class="transport">
                 <seek-bar></seek-bar>
-                <player-controls></player-controls>
+                <!-- context="full": this view *is* the player, so the
+                     transport is the page rather than a strip of it --
+                     primary controls large, shuffle and repeat beneath
+                     at normal size (#56). It is a property rather than
+                     a media query because the bottom bar wants a
+                     different answer at this same viewport. -->
+                <player-controls context="full"></player-controls>
+                <!-- Rendered unconditionally and absent on its own
+                     terms where the device owns the volume (#64): the
+                     control asks the player, not this view and not the
+                     viewport. A hidden host draws no gap, so that is
+                     29px of a 439px screen back to the album art
+                     (#172). -->
                 <volume-control></volume-control>
             </div>
         `;

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

@@ -13,6 +13,7 @@ import {
     isQueueSourceNavigable,
     navigateToQueueSource,
 } from '@utils/queue-source-link';
+import { PHONE_QUERY } from '@utils/breakpoints';
 import { PlayerController } from '@store/controllers/player-controller';
 import { creditStore } from '@store/credit-store';
 import { QueueController } from '@store/controllers/queue-controller';
@@ -80,6 +81,19 @@ export class NowPlaying extends LitElement {
 
     private reduceMotionQuery?: MediaQueryList;
 
+    /**
+     * Phone width, from the shell's own breakpoint.
+     *
+     * This is in JS rather than in the stylesheet because what changes
+     * is the *content*, not its appearance: the title, artist and
+     * source render as plain text instead of as links, and no CSS rule
+     * can take a click handler off an element.
+     */
+    @state()
+    private phone = false;
+
+    private phoneQuery?: MediaQueryList;
+
     /** Whether each field is actively mid-scroll (class toggle). */
     @state()
     private titleScrolling = false;
@@ -174,12 +188,44 @@ export class NowPlaying extends LitElement {
         cursor: pointer;
         /* The art shows through; this is a target, not a picture. */
         color: transparent;
+        /* **Above the art, or it is not a target at all** (#150).
+
+           This button is absolutely positioned with z-index auto and
+           the art is a *later* sibling, so the two tie on paint order
+           and the later one wins. With an <img> that costs nothing --
+           an image is not a hit-test obstacle here -- but a track with
+           no artwork renders a placeholder wa-icon, which is, and it
+           takes every click aimed at the button underneath it.
+
+           The failure is therefore per *track*, not per build: on a
+           phone the only way into the full-screen now-playing view
+           stopped working whenever the current song had no cover.
+           Measured with elementFromPoint at the button's centre --
+           wa-icon with a placeholder, button.expand with an image, and
+           button.expand either way once this line exists.
+
+           z-index rather than pointer-events: none on the art, which
+           would take the cover preview's mouseenter with it; and
+           rather than reordering the DOM, which would leave the same
+           tie to be won by the same accident in the other direction. */
+        z-index: 1;
       }
 
       .expand:focus-visible {
         outline: 2px solid var(--yj-accent, #ffd43b);
         outline-offset: 2px;
       }
+
+      /* The favourite is one of the three controls #59 keeps on the
+         phone's bar, and it was the **smallest control in the app**:
+         measured at 424x439, 18x14px, against the 48x48 art beside it.
+         Zero padding around an icon-sized glyph is a reasonable mouse
+         target and is not a thumb target at all. */
+      .fav-btn {
+        min-width: 44px;
+        min-height: 44px;
+        font-size: var(--yj-icon-md);
+      }
     }
 
     .cover-preview-panel {
@@ -341,6 +387,12 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = this.reduceMotionQuery?.matches ?? false;
         this.reduceMotionQuery?.addEventListener('change', this.handleReduceMotionChange);
 
+        // Same reasoning as above: looked up here, not at module load,
+        // so a test can install its own matchMedia first.
+        this.phoneQuery = window.matchMedia?.(PHONE_QUERY);
+        this.phone = this.phoneQuery?.matches ?? false;
+        this.phoneQuery?.addEventListener('change', this.handlePhoneChange);
+
         this.resizeObserver = new ResizeObserver(() => {
             this.geometryDirty = true;
             this.requestUpdate();
@@ -364,6 +416,7 @@ export class NowPlaying extends LitElement {
         this.attachDragListeners(false);
         window.removeEventListener(SCROLL_CHANGE_EVENT, this.handleScrollModeEvent);
         this.reduceMotionQuery?.removeEventListener('change', this.handleReduceMotionChange);
+        this.phoneQuery?.removeEventListener('change', this.handlePhoneChange);
         this.resizeObserver?.disconnect();
         this.stopScrollCycle('title');
         this.stopScrollCycle('artist');
@@ -404,8 +457,30 @@ export class NowPlaying extends LitElement {
             return html`
         <div class="sr-only" role="status" aria-live="polite">${announcement}</div>
         <div class="now-playing">
-          <div class="cover-art">
+          <!-- **The way to Now Playing does not depend on what is
-            <div class="cover-placeholder"><wa-icon name="music"></wa-icon></div>
+               playing.** This branch used to render the placeholder
+               with no button on it, so on a phone there was no route to
+               the full-screen view while nothing was loaded -- and once
+               #59 took the queue button off the bar, that made the
+               queue itself unreachable, because Now Playing is where it
+               is reached from. The queue is persisted across restarts,
+               so "a queue with tracks in it and nothing playing" is an
+               ordinary state to launch into, not a corner.
+
+               Plan 018's matrix promises no action is unreachable at
+               any supported size, and the promise is what makes #59
+               allowed to remove a control at all. -->
+          <div class="cover-art-wrapper">
+            <button
+              type="button"
+              class="expand"
+              data-testid="open-now-playing"
+              aria-label="Open now playing"
+              @click=${this.openNowPlaying}
+            ></button>
+            <div class="cover-art">
+              <div class="cover-placeholder"><wa-icon name="music"></wa-icon></div>
+            </div>
           </div>
         </div>
         <div
@@ -488,7 +563,7 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleTitleMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('title')}
             >
-              <span class="scroll-content">${trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
+              <span class="scroll-content">${this.phone ? track.title : trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
             </span>
             <span
               class="track-artist ${artistScrolling ? 'will-scroll' : ''} ${this.artistScrolling ? 'scrolling' : ''}"
@@ -498,14 +573,15 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleArtistMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('artist')}
             >
-              <span class="scroll-content">${creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
+              <span class="scroll-content">${this.phone ? track.artist || 'Unknown Artist' : creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
             </span>
             ${describeQueueSource(this.queue.source)
                 ? html`
                   <span
-                    class="track-source ${isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
+                    class="track-source ${!this.phone && isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
                     data-testid="now-playing-source"
                     @click=${(e: MouseEvent) => {
+                        if (this.phone) return;
                         if (!isQueueSourceNavigable(this.queue.source)) return;
                         navigateToQueueSource(
                             e.currentTarget as EventTarget,
@@ -571,6 +647,10 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = e.matches;
     };
 
+    private handlePhoneChange = (e: MediaQueryListEvent): void => {
+        this.phone = e.matches;
+    };
+
     private shouldScroll(field: 'title' | 'artist'): boolean {
         const overflows = field === 'title' ? this.titleOverflows : this.artistOverflows;
 
@@ -606,6 +686,12 @@ export class NowPlaying extends LitElement {
             track?.artist ?? '',
             this.shouldScroll('title') ? '1' : '0',
             this.shouldScroll('artist') ? '1' : '0',
+            // Crossing the breakpoint swaps a link for a bare string,
+            // and a link is not guaranteed to measure the same as the
+            // text inside it. The marquee travels a distance read from
+            // that measurement, so this belongs in the key even though
+            // the words are identical either side.
+            this.phone ? '1' : '0',
         ].join('\u0000');
     }
 

frontend/src/components/page-header/page-header.ts

@@ -1,8 +1,17 @@
 import { LitElement, html, css, nothing } from 'lit';
-import { customElement, property } from 'lit/decorators.js';
+import { customElement, property, query, state } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
+import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 
 import { designTokens } from '../../styles/tokens.css';
+import {
+    MenuKeyboard,
+    contextMenuStyles,
+} from '../../utils/context-menu-controller';
+import { ICON_MORE_ACTIONS } from '../../utils/icon-language';
+import '../search-dialog/search-trigger';
 
 /**
  * The one arrangement every primary view uses to say what it is.
@@ -18,6 +27,19 @@ import { designTokens } from '../../styles/tokens.css';
  * Title, count, sort, actions — in that order, in one component, so a
  * new view gets the shape by using it rather than by copying whichever
  * neighbour it happened to read.
+ *
+ * **Actions are data, and `<slot name="actions">` is the exception.**
+ * Playlists' three buttons totalled 390px inside a header that gets
+ * 700px at 900×600 and clipped "New Smart Playlist" to 114 of its 162
+ * (#69) — a live defect at a size the app promises, against plan 018's
+ * *no action is ever unreachable at any supported size*. The header
+ * cannot fix that for slotted markup: it cannot move another
+ * component's light-DOM children into a dropdown and keep their
+ * behaviour, and arbitrary markup offers nothing generic to render as
+ * a menu item. So a host declares `PageAction[]` and the header picks
+ * the rendering. The slot survives for markup a data list genuinely
+ * cannot express, at the stated cost that **a slotted action does not
+ * collapse** and must therefore fit at 800×600.
  */
 
 export interface SortOption {
@@ -27,6 +49,50 @@ export interface SortOption {
 
 export type SortDirection = 'asc' | 'desc';
 
+/**
+ * An action that only makes sense while it is a button.
+ *
+ * A drop target is the case: you cannot drag a track onto a closed
+ * menu, so the affordance is absent from the overflow rather than
+ * approximated there. The header wires these onto the button it
+ * renders and owns none of them — the same division the sort control
+ * already lives by.
+ */
+export interface PageActionDrop {
+    /** True while an acceptable payload is over the button. */
+    active?: boolean;
+    onDragOver: (e: DragEvent) => void;
+    onDragLeave: (e: DragEvent) => void;
+    onDrop: (e: DragEvent) => void;
+}
+
+/**
+ * One thing a view can do, as data rather than as markup.
+ *
+ * `<slot name="actions">` cannot be collapsed, and that is a fact about
+ * the API rather than an effort estimate (#69): a component cannot move
+ * another component's light-DOM children into a dropdown and keep their
+ * behaviour, and there is nothing generic in arbitrary markup to render
+ * as a menu item. Declaring an action instead is what lets the header
+ * choose between the two renderings.
+ */
+export interface PageAction {
+    id: string;
+    label: string;
+    /** From `utils/icon-language`, never a literal. */
+    icon: string;
+    onSelect: () => void;
+    /**
+     * Higher survives longer. The lowest collapses first, ties broken
+     * by declaration order from the right, so a host that says nothing
+     * gets "the last one written goes first".
+     */
+    priority?: number;
+    disabled?: boolean;
+    title?: string;
+    drop?: PageActionDrop;
+}
+
 @customElement('page-header')
 export class PageHeader extends LitElement {
     /**
@@ -80,8 +146,91 @@ export class PageHeader extends LitElement {
     @property({ type: Boolean })
     busy = false;
 
+    /**
+     * What this view can do, in the order it wants them shown.
+     *
+     * The header decides what *fits*; the host decides what *happens*.
+     * That is the rule the sort control already lives by — it asks for
+     * a sort rather than performing one — and actions follow it, which
+     * is why an action carries a handler rather than the header
+     * carrying a verb it would have to interpret.
+     */
+    @property({ attribute: false })
+    actions: PageAction[] = [];
+
+    /** Action ids currently in the overflow menu. Derived, never set by a host. */
+    @state()
+    private collapsed: ReadonlySet<string> = new Set();
+
+    /**
+     * Whether the count has been given up. Derived, like `collapsed`.
+     *
+     * It is the last thing to yield and the only thing here that is
+     * neither an identity nor an action — see `measureFit`.
+     */
+    @state()
+    private countCollapsed = false;
+
+    @state()
+    private menuOpen = false;
+
+    @query('.page-header')
+    private headerEl?: HTMLElement;
+
+    @query('.more-button')
+    private moreButton?: HTMLButtonElement;
+
+    @query('#page-header-overflow')
+    private menuPanel?: HTMLElement;
+
+    @query('menu-surface')
+    private popup?: MenuSurface;
+
+    private menuKeyboard = new MenuKeyboard(() => this.closeMenu());
+
+    private resizeObserver?: ResizeObserver;
+
+    /**
+     * Whether the outside-click listener is attached.
+     *
+     * A `removeEventListener` with no matching `add` is not harmless
+     * here: `view-lifecycle.test.ts` counts document listeners across a
+     * view's life and an unconditional detach on disconnect shows up as
+     * `held: -1`, which is the same accounting that would hide a real
+     * leak in the other direction.
+     */
+    private outsideCloseAttached = false;
+
+    /**
+     * What the last fit was measured against.
+     *
+     * `updated()` runs on every pass, so it has to say what it depends
+     * on or it re-measures — and a measurement here forces synchronous
+     * layout. Width changes arrive through the ResizeObserver; this key
+     * covers everything *else* in the flex row that can change how much
+     * of it the actions are left.
+
+     */
+    private lastFitKey = '';
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+
+        this.resizeObserver = new ResizeObserver(() => this.measureFit());
+        this.resizeObserver.observe(this);
+    }
+
+    override disconnectedCallback(): void {
+        super.disconnectedCallback();
+
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = undefined;
+        this.detachOutsideClose();
+    }
+
     static override styles = [
         designTokens,
+        contextMenuStyles,
         css`
             :host {
                 display: block;
@@ -96,12 +245,26 @@ export class PageHeader extends LitElement {
                 border-bottom: 1px solid var(--yj-border-subtle, #333);
             }
 
+            /* The title gives way before an action does.
+
+               Everything in this row was flex-shrink: 0, so whatever
+               came last lost — and the actions come last, which is how
+               the "More actions" button ended up 76px off the right
+               edge of a 320px viewport with every action already
+               collapsed into it. The title is the one thing here the
+               navigation also says (the sidebar item is selected, the
+               bottom-nav tab is current), so it is the cheapest thing
+               to truncate; the count, the sort and the actions are each
+               the only place they are said. */
             h1 {
                 margin: 0;
                 font-size: var(--yj-text-xl, 18px);
                 font-weight: 600;
                 color: var(--yj-text-primary, #fff);
                 white-space: nowrap;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                min-width: 0;
             }
 
             .count {
@@ -191,6 +354,98 @@ export class PageHeader extends LitElement {
             ::slotted(*) {
                 flex-shrink: 0;
             }
+
+            .actions {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+                flex-shrink: 0;
+            }
+
+            .action,
+            .more-button {
+                background: none;
+                border: 1px solid var(--yj-border-subtle, #555);
+                border-radius: 4px;
+                color: var(--yj-text-primary, #fff);
+                padding: 6px 12px;
+                font-size: var(--yj-text-md, 13px);
+                font-family: inherit;
+                cursor: pointer;
+                display: flex;
+                align-items: center;
+                gap: 6px;
+                white-space: nowrap;
+                flex-shrink: 0;
+            }
+
+            .more-button {
+                padding: 6px 10px;
+            }
+
+            /* The display: flex above outranks the UA stylesheet's
+               rule for [hidden], and hiding is how an action
+               collapses. (No backticks in here: one ends the css
+               literal, and what you get is "css(...) is not a
+               function" a long way from the cause.) */
+            .action[hidden],
+            .more-button[hidden] {
+                display: none;
+            }
+
+            .action:hover,
+            .more-button:hover,
+            .action.drag-over {
+                border-color: var(--yj-accent, #ffd43b);
+                color: var(--yj-accent-text, #ffd43b);
+            }
+
+            .action.drag-over {
+                background-color: var(
+                    --yj-accent-bg-strong,
+                    rgba(255, 212, 59, 0.15)
+                );
+            }
+
+            .action:disabled {
+                opacity: 0.5;
+                cursor: default;
+            }
+
+            .action:focus-visible,
+            .more-button:focus-visible {
+                outline: 2px solid var(--yj-accent, #ffd43b);
+                outline-offset: -1px;
+            }
+
+            menu-surface {
+                z-index: 200;
+            }
+
+            /* A component states what it drops at phone width itself,
+               in its own stylesheet, because a media query inside a
+               shadow root is answered by the viewport and the shell
+               cannot reach in. Here that is one word: the sort control
+               is 172px of a 320px header, and "Sort:" is ~40px of it
+               for a label the adjacent direction arrow already implies.
+               It stays in the accessibility tree — it is the select's
+               accessible name, so hiding it outright would rename the
+               control to nothing — which is config-field's bug, one
+               component over. clip-path rather than display: none for
+               the reason styles/sr-only.css.ts gives. */
+            @media (max-width: 599px) {
+                .sort-label {
+                    position: absolute;
+                    width: 1px;
+                    height: 1px;
+                    margin: -1px;
+                    padding: 0;
+                    overflow: hidden;
+                    clip-path: inset(50%);
+                    white-space: nowrap;
+                    border: 0;
+                }
+            }
         `,
     ];
 
@@ -212,11 +467,348 @@ export class PageHeader extends LitElement {
                 ${this.renderCount()}
                 <div class="spacer"></div>
                 ${this.renderScope()} ${this.renderSort()}
+                <!-- #57. Below 600px the top bar is out of the layout,
+                     so the search box has to be reachable from here.
+                     It renders nothing at every other width and on
+                     every view search-store says has nothing to
+                     search, which is why no host declares it: the map
+                     of searchable views already exists and this is one
+                     more reader of it, not a second copy.
+
+                     Before the actions, and never one of them: an
+                     action can collapse into the overflow menu, and on
+                     a phone that menu is already where the page's own
+                     actions live -- search behind an ellipsis is the
+                     top bar's problem moved rather than fixed. -->
+                <search-trigger></search-trigger>
+                ${this.renderActions()}
                 <slot name="actions"></slot>
             </header>
         `;
     }
 
+    protected override updated(): void {
+        const key = [
+            this.heading,
+            this.count,
+            this.countNoun,
+            this.countPlural,
+            this.searchTerm,
+            this.sortOptions.length,
+            this.sortField,
+            this.sortDirection,
+            this.busy,
+            this.actions.map((a) => `${a.id}:${a.label}:${a.disabled ?? false}`).join(','),
+        ].join('|');
+
+        if (key === this.lastFitKey) return;
+
+        this.lastFitKey = key;
+        this.measureFit();
+    }
+
+    // =================================================================
+    // What fits
+    // =================================================================
+
+    /**
+     * Decide which actions are buttons and which are menu items.
+     *
+     * Two things about the shape of this are load-bearing.
+     *
+     * **Every pass starts from all-visible**, so the collapsed set is a
+     * pure function of the current width rather than of the order the
+     * widths arrived in. A rule that only ever *added* to the set would
+     * never give an action back when the window grew, and one that
+     * adjusted by a step would need a hysteresis band to stop it
+     * oscillating on the pixel where a button exactly fits.
+     *
+     * **It 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 would let the
+     * intermediate all-visible state paint, so the fix would flash the
+     * overflow it exists to prevent. The reactive state is set once, at
+     * the end, and the next render agrees with what was measured.
+     *
+     * The budget is the *header's* overflow and not the actions row's,
+     * because the count and the sort control are `flex-shrink: 0` and
+     * are therefore competing for the same width — only `.scope` gives
+     * way, which is what it has an ellipsis for.
+     */
+    private measureFit(): void {
+        const header = this.headerEl;
+
+        if (!header) return;
+
+        const buttons = new Map<string, HTMLElement>();
+
+        for (const el of this.renderRoot.querySelectorAll<HTMLElement>(
+            '[data-action-id]',
+        )) {
+            const id = el.dataset['actionId'];
+
+            if (id !== undefined) buttons.set(id, el);
+        }
+
+        const more = this.moreButton;
+        const title = this.renderRoot.querySelector('h1');
+        const count = this.renderRoot.querySelector<HTMLElement>('.count');
+
+        /**
+         * Nothing is clipped — which is not the same as the header not
+         * overflowing, and the difference is a trap worth naming.
+         *
+         * Once the title can ellipsis, it absorbs the pressure and
+         * `scrollWidth` reports a header that fits perfectly while the
+         * heading reads "Playlis…". That is this issue's own failure
+         * mode moved from the button to the title, and it is invisible
+         * to exactly the same measurement that missed it the first time.
+         * So the title's own truncation counts as not fitting, and
+         * collapsing an action is tried before the title gives way.
+         */
+        const fits = () =>
+            header.scrollWidth <= header.clientWidth &&
+            (title === null || title.scrollWidth <= title.clientWidth + 1);
+
+        for (const el of buttons.values()) el.hidden = false;
+
+        if (more) more.hidden = true;
+
+        if (count) count.hidden = false;
+
+        const collapsed = new Set<string>();
+
+        if (!fits()) {
+            if (more) more.hidden = false;
+
+            for (const action of this.collapseOrder()) {
+                collapsed.add(action.id);
+
+                const el = buttons.get(action.id);
+
+                if (el) el.hidden = true;
+
+                if (fits()) break;
+            }
+        }
+
+        this.commitCollapsed(collapsed, this.collapseCount(count, fits));
+    }
+
+    /**
+     * The last thing to give way, after every action is in the menu and
+     * the title has already run out.
+     *
+     * There are four things competing for this row and three of them
+     * cannot go. The **title** yields first and is allowed to ellipsis
+     * away entirely at 320px, because the navigation also says which
+     * page you are on. The **sort** control and the **actions** are
+     * each the only place they are said, so an action collapses into
+     * the menu rather than disappearing and the sort control stays.
+     * That leaves the **count**, which is the one purely informational
+     * item on the row — an empty page says so in its empty state, and a
+     * full one is being looked at.
+     *
+     * It became reachable rather than theoretical with #57: below 600px
+     * the header also carries the phone's search button, and on
+     * Playlists at 320px that is 43px more than the row has. Measured
+     * there: title 0, count 50, sort 143, search 40, "More actions" 38,
+     * five 12px gaps and 32px of gutters — 363 in 320, with the More
+     * button ending 27px past the edge. Something has to go, and this
+     * is the only candidate that is not an action.
+     *
+     * @returns whether the count was given up.
+     */
+    private collapseCount(
+        count: HTMLElement | null,
+        fits: () => boolean,
+    ): boolean {
+        if (count === null || fits()) return false;
+
+        count.hidden = true;
+
+        return true;
+    }
+
+    /** Lowest priority first; ties broken from the right. */
+    private collapseOrder(): PageAction[] {
+        return this.actions
+            .map((action, index) => ({ action, index }))
+            .sort(
+                (a, b) =>
+                    (a.action.priority ?? 0) - (b.action.priority ?? 0) ||
+                    b.index - a.index,
+            )
+            .map(({ action }) => action);
+    }
+
+    private commitCollapsed(next: Set<string>, countHidden: boolean): void {
+        this.countCollapsed = countHidden;
+
+        const same =
+            next.size === this.collapsed.size &&
+            [...next].every((id) => this.collapsed.has(id));
+
+        if (same) return;
+
+        this.collapsed = next;
+
+        // Nothing left to show in it. Closing rather than leaving an
+        // empty menu open is the same rule the shelves follow.
+        if (next.size === 0 && this.menuOpen) this.closeMenu();
+    }
+
+    // =================================================================
+    // Rendering
+    // =================================================================
+
+    private renderActions() {
+        if (this.actions.length === 0) return nothing;
+
+        const overflowed = this.actions.filter((a) => this.collapsed.has(a.id));
+
+        return html`
+            <div class="actions">
+                ${this.actions.map((a) => this.renderActionButton(a))}
+                <!-- A sheet below 600px, like every other menu in the
+                     app (#60). The clipping that issue is about does
+                     not bite here — this one opens downward from the
+                     top of a full-height view, so it has somewhere to
+                     go even without top-layer promotion — but the touch
+                     targets do: on a phone *every* action of a page
+                     that overflows lives in here, at wa-dropdown-item
+                     defaults. One surface, so there is no second
+                     answer to what a menu looks like. -->
+                <menu-surface
+                    placement="bottom-end"
+                    .active=${this.menuOpen}
+                >
+                    <button
+                        slot="anchor"
+                        class="more-button"
+                        type="button"
+                        data-testid="page-actions-more"
+                        aria-label="More actions"
+                        aria-haspopup="menu"
+                        aria-expanded=${this.menuOpen ? 'true' : 'false'}
+                        aria-controls="page-header-overflow"
+                        ?hidden=${overflowed.length === 0}
+                        @click=${this.onMoreClick}
+                    >
+                        <wa-icon name=${ICON_MORE_ACTIONS}></wa-icon>
+                    </button>
+                    <div
+                        id="page-header-overflow"
+                        class="context-menu-panel"
+                        role="menu"
+                        aria-label="More actions"
+                    >
+                        ${overflowed.map(
+                            (a) => html`
+                                <wa-dropdown-item
+                                    ?disabled=${a.disabled ?? false}
+                                    @click=${() => this.onActionSelect(a)}
+                                >
+                                    <wa-icon
+                                        slot="icon"
+                                        name=${a.icon}
+                                    ></wa-icon>
+                                    ${a.label}
+                                </wa-dropdown-item>
+                            `,
+                        )}
+                    </div>
+                </menu-surface>
+            </div>
+        `;
+    }
+
+    private renderActionButton(a: PageAction) {
+        const drop = a.drop;
+
+        return html`
+            <button
+                class="action ${drop?.active === true ? 'drag-over' : ''}"
+                type="button"
+                data-action-id=${a.id}
+                data-testid=${`page-action-${a.id}`}
+                title=${a.title ?? nothing}
+                ?disabled=${a.disabled ?? false}
+                ?hidden=${this.collapsed.has(a.id)}
+                @click=${() => a.onSelect()}
+                @dragover=${(e: DragEvent) => drop?.onDragOver(e)}
+                @dragleave=${(e: DragEvent) => drop?.onDragLeave(e)}
+                @drop=${(e: DragEvent) => drop?.onDrop(e)}
+            >
+                <wa-icon name=${a.icon}></wa-icon>
+                ${a.label}
+            </button>
+        `;
+    }
+
+    // =================================================================
+    // The overflow menu
+    // =================================================================
+
+    private onActionSelect(a: PageAction): void {
+        if (a.disabled === true) return;
+
+        this.closeMenu();
+        a.onSelect();
+    }
+
+    private onMoreClick = (): void => {
+        if (this.menuOpen) {
+            this.closeMenu();
+
+            return;
+        }
+
+        this.menuOpen = true;
+
+        void this.updateComplete.then(() => {
+            if (!this.menuOpen) return;
+
+            this.popup?.reposition();
+            this.menuKeyboard.open(this.menuPanel ?? null, this.moreButton);
+            this.attachOutsideClose();
+        });
+    };
+
+    private closeMenu(): void {
+        if (!this.menuOpen) return;
+
+        this.detachOutsideClose();
+        this.menuKeyboard.close();
+        this.menuOpen = false;
+    }
+
+    /**
+     * A click anywhere else closes it. `composedPath` rather than
+     * `contains`, because the trigger and the panel are both inside
+     * this shadow root and a click retargets at the host.
+     */
+    private onOutsideDown = (e: Event): void => {
+        if (e.composedPath().includes(this.menuPanel as EventTarget)) return;
+        if (e.composedPath().includes(this.moreButton as EventTarget)) return;
+
+        this.closeMenu();
+    };
+
+    private attachOutsideClose(): void {
+        if (this.outsideCloseAttached) return;
+
+        this.outsideCloseAttached = true;
+        document.addEventListener('mousedown', this.onOutsideDown, true);
+    }
+
+    private detachOutsideClose(): void {
+        if (!this.outsideCloseAttached) return;
+
+        this.outsideCloseAttached = false;
+        document.removeEventListener('mousedown', this.onOutsideDown, true);
+    }
+
     private renderCount() {
         if (this.count === null) return nothing;
 
@@ -227,7 +819,16 @@ export class PageHeader extends LitElement {
 
         const noun = this.count === 1 ? this.countNoun : plural;
 
-        return html`<span class="count" data-testid="page-count"
+        // Rendered whether or not it fits, and hidden with an
+        // attribute -- the same shape the action buttons use, and for
+        // the same reason: `measureFit` starts every pass from
+        // all-visible, so it needs a node to un-hide. Returning
+        // `nothing` here would take the count away for the rest of the
+        // session the first time a 320px window appeared.
+        return html`<span
+            class="count"
+            data-testid="page-count"
+            ?hidden=${this.countCollapsed}
             >${this.count.toLocaleString()} ${noun}</span
         >`;
     }
@@ -258,7 +859,10 @@ export class PageHeader extends LitElement {
         if (this.sortOptions.length === 1) {
             return html`
                 <div class="sort">
-                    <span>Sort: ${this.sortOptions[0]?.label}</span>
+                    <span
+                        ><span class="sort-label">Sort: </span
+                        >${this.sortOptions[0]?.label}</span
+                    >
                     ${this.renderDirectionButton(ascending)}
                 </div>
             `;
@@ -267,7 +871,7 @@ export class PageHeader extends LitElement {
         return html`
             <div class="sort">
                 <label>
-                    Sort:
+                    <span class="sort-label">Sort:</span>
                     <select
                         data-testid="page-sort"
                         .value=${this.sortField}

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

@@ -7,7 +7,8 @@ import {
 } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@lit-labs/virtualizer';
 import type { LitVirtualizer } from '@lit-labs/virtualizer';
@@ -27,6 +28,7 @@ import { queueStore } from '@store/queue-store';
 import { creditStore } from '@store/credit-store';
 import { PlayerController } from '@store/controllers/player-controller';
 import { SearchController } from '@store/controllers/search-controller';
+import '../search-dialog/search-trigger';
 import { SelectionController } from '@utils/selection-controller';
 import type { SelectionHost } from '@utils/selection-controller';
 import {
@@ -34,7 +36,7 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { notificationStore } from '@store/notification-store';
@@ -144,10 +146,10 @@ export class PlaylistDetails
     private dragImageEl: HTMLElement | null = null;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     @query('track-details')
     private trackDetailsDialog!: TrackDetails;
@@ -162,11 +164,11 @@ export class PlaylistDetails
     // ContextMenuHost interface
     // =================================================================
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -1039,6 +1041,16 @@ export class PlaylistDetails
             min-width: 0;
         }
 
+        /* #57. This view is in search-store's map and filters on the
+           term, but it is a detail view and so has no page-header to
+           carry the phone's search button. Pushed to the end of the
+           header row, which is where page-header puts it too. */
+        .header-end {
+            margin-left: auto;
+            display: flex;
+            align-items: center;
+        }
+
         .playlist-title {
             font-size: 24px;
             font-weight: 700;
@@ -1383,6 +1395,9 @@ export class PlaylistDetails
                           `
                         : ''}
                 </div>
+                <div class="header-end">
+                    <search-trigger></search-trigger>
+                </div>
             </div>
             ${searchBar}
             <div
@@ -1603,11 +1618,8 @@ export class PlaylistDetails
 
     private renderContextMenu() {
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .contextMenuOpen}
             >
@@ -1769,13 +1781,12 @@ export class PlaylistDetails
                               </div>
                           `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .playlistSubmenuOpen}
             >
@@ -1802,7 +1813,7 @@ export class PlaylistDetails
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 }

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

@@ -2,7 +2,9 @@ import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state, query } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 
 import {
@@ -40,7 +42,10 @@ import type { DuplicateTracksDialog } from '@components/duplicate-tracks-dialog/
 import {
     ICON_NEW,
     ICON_PLAYLIST,
+    ICON_SMART_PLAYLIST,
 } from '@utils/icon-language';
+import '@components/page-header/page-header';
+import type { PageAction } from '@components/page-header/page-header';
 
 const SCROLL_DEBOUNCE_MS = 100;
 
@@ -137,7 +142,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
     private pendingDropPaths: string[] = [];
 
     @query('#playlist-context-menu')
-    private playlistContextMenuPopup!: WaPopup;
+    private playlistContextMenuPopup!: MenuSurface;
 
     @query('duplicate-tracks-dialog')
     private duplicateDialog!: DuplicateTracksDialog;
@@ -194,11 +199,6 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
             contain: layout style;
         }
 
-        .header-actions {
-            display: flex;
-            gap: 8px;
-        }
-
         .header-spinner {
             display: inline-block;
             width: 14px;
@@ -209,33 +209,6 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
             animation: spin 0.6s linear infinite;
         }
 
-        .new-playlist-button {
-            background: none;
-            border: 1px solid var(--yj-border-subtle, #555);
-            border-radius: 4px;
-            color: var(--yj-text-primary, #fff);
-            padding: 6px 12px;
-            font-size: 13px;
-            cursor: pointer;
-            display: flex;
-            align-items: center;
-            gap: 6px;
-            font-family: inherit;
-        }
-
-        .new-playlist-button:hover,
-        .new-playlist-button.drag-over {
-            border-color: var(--yj-accent, #ffd43b);
-            color: var(--yj-accent-text, #ffd43b);
-        }
-
-        .new-playlist-button.drag-over {
-            background-color: var(
-                --yj-accent-bg-strong,
-                rgba(255, 212, 59, 0.15)
-            );
-        }
-
         .create-form {
             display: flex;
             align-items: center;
@@ -455,25 +428,6 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
             min-width: 0;
         }
 
-        .import-button {
-            background: none;
-            border: 1px solid var(--yj-border-subtle, #555);
-            border-radius: 4px;
-            color: var(--yj-text-primary, #fff);
-            padding: 6px 12px;
-            font-size: 13px;
-            cursor: pointer;
-            display: flex;
-            align-items: center;
-            gap: 6px;
-            font-family: inherit;
-        }
-
-        .import-button:hover {
-            border-color: var(--yj-accent, #ffd43b);
-            color: var(--yj-accent-text, #ffd43b);
-        }
-
         .import-error {
             padding: 0.5em 0.75em;
             margin: 0.5em 16px 0;
@@ -1022,10 +976,11 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
     ) => {
         const related =
             e.relatedTarget as Node | null;
-        const btn =
+        // The button the event was bound to, rather than a selector for
-            this.shadowRoot?.querySelector(
+        // it: `page-header` renders it now, so it is not in this shadow
-                '.new-playlist-button',
+        // root at all and the old `.new-playlist-button` lookup would
-            );
+        // find nothing and leave the highlight stuck on.
+        const btn = e.currentTarget as Element | null;
 
         if (btn && !btn.contains(related)) {
             this.dragOverNewButton = false;
@@ -1106,7 +1061,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
         );
     }
 
-    private closePlaylistContextMenu() {
+    private closePlaylistContextMenu = () => {
         if (!this.playlistContextMenuOpen) return;
 
         this.menuKeyboard.close();
@@ -1119,7 +1074,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
         if (popup) {
             popup.active = false;
         }
-    }
+    };
 
     private async onPlaylistContextAction(
         action: string,
@@ -1470,6 +1425,49 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
         this.saveSortPreferences();
     };
 
+    /**
+     * The three things this page can do, as data.
+     *
+     * The priority order is what #69's Direction asks for and it is
+     * only interesting for one of them: **New Playlist is highest
+     * because it is the drop target**. You cannot drag a track onto a
+     * closed menu, so collapsing it is the one collapse here that
+     * removes a capability rather than relocating it. Import is lowest
+     * because it is the rarest, and at 900×600 it is the only one that
+     * has to go.
+     */
+    private headerActions(): PageAction[] {
+        return [
+            {
+                id: 'import',
+                label: 'Import',
+                icon: 'file-import',
+                priority: 0,
+                onSelect: () => void this.handleImportPlaylist(),
+            },
+            {
+                id: 'new-playlist',
+                label: 'New Playlist',
+                icon: ICON_NEW,
+                priority: 2,
+                onSelect: () => this.handleNewPlaylistClick(),
+                drop: {
+                    active: this.dragOverNewButton,
+                    onDragOver: this.onNewButtonDragOver,
+                    onDragLeave: this.onNewButtonDragLeave,
+                    onDrop: this.onNewButtonDrop,
+                },
+            },
+            {
+                id: 'new-smart-playlist',
+                label: 'New Smart Playlist',
+                icon: ICON_SMART_PLAYLIST,
+                priority: 1,
+                onSelect: () => this.handleNewSmartPlaylistClick(),
+            },
+        ];
+    }
+
     override render() {
         return html`
             <page-header
@@ -1484,33 +1482,8 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                 search-term=${this.searchCtrl.term}
                 ?busy=${this.refreshing}
                 @sort-change=${this.onPageHeaderSort}
+                .actions=${this.headerActions()}
             >
-                <div slot="actions" class="header-actions">
-                    <button
-                        class="import-button"
-                        @click=${this.handleImportPlaylist}
-                    >
-                        <wa-icon name="file-import"></wa-icon>
-                        Import
-                    </button>
-                    <button
-                        class="new-playlist-button ${this.dragOverNewButton ? 'drag-over' : ''}"
-                        @click=${this.handleNewPlaylistClick}
-                        @dragover=${this.onNewButtonDragOver}
-                        @dragleave=${this.onNewButtonDragLeave}
-                        @drop=${this.onNewButtonDrop}
-                    >
-                        <wa-icon name=${ICON_NEW}></wa-icon>
-                        New Playlist
-                    </button>
-                    <button
-                        class="new-playlist-button"
-                        @click=${this.handleNewSmartPlaylistClick}
-                    >
-                        <wa-icon name="filter"></wa-icon>
-                        New Smart Playlist
-                    </button>
-                </div>
             </page-header>
 
             ${this.importError
@@ -1529,13 +1502,11 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                   </div>`
                 : this.renderPlaylistList()}
 
-            <wa-popup
+            <menu-surface
                 id="playlist-context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this
                     .playlistContextMenuOpen}
+                @menu-dismiss=${this.closePlaylistContextMenu}
             >
                 ${this.playlistContextMenuOpen
                     ? html`
@@ -1593,7 +1564,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
             <duplicate-tracks-dialog
                 @playlist-action-complete=${() =>
@@ -1765,7 +1736,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                         : entry.summary.IsSmart
                           ? html`<wa-icon
                                 class="playlist-icon"
-                                name="filter"
+                                name=${ICON_SMART_PLAYLIST}
                             ></wa-icon>`
                           : nothing}
                     ${isRenaming

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

@@ -9,7 +9,8 @@ import {
 } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import { QueueController } from '@store/controllers/queue-controller';
 import { creditStore } from '@store/credit-store';
@@ -34,7 +35,7 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import {
@@ -140,13 +141,13 @@ export class QueuePanel
     private delegationAttached = false;
 
     @query('#add-to-playlist-popup')
-    private addToPlaylistPopup!: WaPopup;
+    private addToPlaylistPopup!: MenuSurface;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     /** Unsubscribes the credit-arrival repaint. */
     private creditsUnsub?: () => void;
@@ -277,6 +278,26 @@ export class QueuePanel
         return this.queue.tracks.length;
     }
 
+    /**
+     * Repaint the rows when the selection changes.
+     *
+     * `<lit-virtualizer>` renders through the `virtualize` directive,
+     * which reacts to its *own* properties and not to the host having
+     * re-rendered, so host state like a selection reaches the rows only
+     * if it is pushed. `track-list` has always done this and both
+     * playlist views had to be taught it.
+     *
+     * **There is a second, accidental mechanism here and it must not be
+     * mistaken for this one**: `.keyFunction` below 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, which is why #43 could not be settled by
+     * reading the code. With both gone the highlight still arrives —
+     * on whatever unrelated render happens next, measured at 134ms,
+     * 3,866ms and 5,816ms against 5–17ms healthy, which a user cannot
+     * tell from broken. `queue-selection.spec.ts` asserts the
+     * *promptness* rather than the eventual state for that reason.
+     */
     onSelectionChanged(): void {
         this.virtualizer?.requestUpdate();
     }
@@ -285,11 +306,11 @@ export class QueuePanel
     // ContextMenuHost interface
     // =================================================================
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -390,6 +411,22 @@ export class QueuePanel
             :host([overlay]) .panel-content {
                 width: 100%;
             }
+
+            /* A screen's way out has to be hittable with a thumb.
+               Measured at 424x439 before #55: these were **25x21px**,
+               and with the panel spanning the whole width the scrim
+               underneath has no uncovered pixels at all -- so it was
+               the only pointer route out of a full-screen surface.
+               Back answers it now as well, which is the other half.
+
+               Sized only in overlay mode: inline these sit in a 320px
+               column beside the content, where a mouse is what reaches
+               them and 44px of header is 44px the queue does not get. */
+            :host([overlay]) .header-action-button {
+                min-width: 44px;
+                min-height: 44px;
+                justify-content: center;
+            }
         }
 
         .resize-handle {
@@ -1056,7 +1093,7 @@ export class QueuePanel
         }
     }
 
-    private closePlaylistPicker() {
+    private closePlaylistPicker = () => {
         if (!this.playlistPickerOpen) return;
 
         this.playlistPickerOpen = false;
@@ -1066,7 +1103,7 @@ export class QueuePanel
         if (popup) {
             popup.active = false;
         }
-    }
+    };
 
     private onPlaylistActionComplete = () => {
         this.closePlaylistPicker();
@@ -2006,9 +2043,11 @@ export class QueuePanel
                     </div>
                 </div>
 
-                <wa-popup
+                <menu-surface
                     id="add-to-playlist-popup"
+                    label="Add to playlist"
                     placement="bottom-end"
+                    @menu-dismiss=${this.closePlaylistPicker}
                     .active=${this.playlistPickerOpen}
                 >
                     ${this.playlistPickerOpen
@@ -2024,7 +2063,7 @@ export class QueuePanel
                               ></playlist-picker>
                           `
                         : nothing}
-                </wa-popup>
+                </menu-surface>
 
                 <div
                     class="list-area"
@@ -2067,11 +2106,8 @@ export class QueuePanel
                 </div>
             </div>
 
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu.contextMenuOpen}
             >
                 ${this.ctxMenu.contextMenuOpen
@@ -2159,13 +2195,12 @@ export class QueuePanel
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu.playlistSubmenuOpen}
             >
                 ${this.ctxMenu.playlistSubmenuOpen &&
@@ -2188,7 +2223,7 @@ export class QueuePanel
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
             <track-details></track-details>
         `;

frontend/src/components/search-bar/search-bar.ts

@@ -62,7 +62,10 @@ export class SearchBar extends LitElement {
             gap: 8px;
             height: 32px;
             min-width: 200px;
-            max-width: 360px;
+            /* A cap for a header, not for the box. search-dialog gives
+               it the whole of a modal, where 360px of a 424px screen
+               would read as a control that failed to size itself. */
+            max-width: var(--yj-search-max-width, 360px);
             width: 100%;
             transition: border-color 0.15s ease;
         }

frontend/src/components/search-dialog/search-dialog.ts

@@ -0,0 +1,210 @@
+/**
+ * The phone's search surface (#57).
+ *
+ * Below 600px there is no top bar to hold a search box — the bar is out
+ * of the layout entirely, which is the single biggest vertical win
+ * available on a 439 CSS px viewport. So the box moves into a modal and
+ * the *trigger* moves into the row that already says which page you are
+ * on (`search-trigger`, beside this file).
+ *
+ * **It is a `wa-dialog`, and that is a mechanism rather than a taste.**
+ * #60 read this out of the Web Awesome source: `wa-popup` renders
+ * `<div popover="manual">` and feature-detects the Popover API, falling
+ * back to `strategy: "fixed"` where there is none — which is the
+ * reference device, Chrome 113, since `popover` is Chrome 114. And
+ * `position: fixed` escapes ancestor *overflow* but not `contain:
+ * paint`, which makes an element a containing block for fixed
+ * descendants **and clips them**; `index.css` puts `contain: layout
+ * style paint` on `.main-panel`, which is the ancestor of every view.
+ * A popup-shaped search panel opened from a view's header would
+ * therefore be structurally clipped on the one device this issue is
+ * about, and **no tier here could see it** — CI's Chromium and WebKit
+ * both have the Popover API, so the popup is top-layered and correct.
+ * `<dialog>`/`showModal()` is Chrome 37 and uses the real top layer, so
+ * this is immune by construction.
+ *
+ * **It carries the real `<search-bar>`**, not a second input. That is
+ * what keeps one debounce, one clear button, one accessible name and
+ * one view-scoped placeholder — and it is why `store/search-store.ts`
+ * is still the only statement of which views can search and what they
+ * search. The modal is a presentation of the control, not a copy of it.
+ *
+ * **The results are the view, not a list in here.** The Direction says
+ * "the box and live results"; the live results already exist, because
+ * the term is view-scoped and the page behind this dialog filters on it
+ * and says so in `page-header`'s "Showing albums matching …" line.
+ * Rendering results in the dialog would be a second implementation of
+ * every view's own filtering, and a worse one — it could not offer the
+ * row actions the view does. So Enter closes and hands the screen back.
+ *
+ * A singleton in `index.html` for the reason `shortcuts-overlay` is:
+ * one instance, one `data-testid`, one document listener, and no
+ * `data-testid="search-input"` resolving to two elements while it is
+ * shut.
+ */
+import { LitElement, css, html, nothing } from 'lit';
+import { customElement, query, state } from 'lit/decorators.js';
+import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
+
+import { designTokens } from '../../styles/tokens.css';
+import { nameDialogsIn } from '@utils/name-dialog';
+import { SearchController } from '@store/controllers/search-controller';
+import type { SearchBar } from '../search-bar/search-bar';
+import '../search-bar/search-bar';
+
+/** The event any trigger dispatches to open this. */
+export const OPEN_SEARCH_EVENT = 'open-search';
+
+@customElement('search-dialog')
+export class SearchDialog extends LitElement {
+    private searchCtrl = new SearchController(this);
+
+    @query('wa-dialog') private dialog?: HTMLElement & { open: boolean };
+
+    @query('search-bar') private bar?: SearchBar;
+
+    @state() private isOpen = false;
+
+    static override styles = [
+        designTokens,
+        css`
+            :host {
+                display: contents;
+            }
+
+            wa-dialog::part(dialog) {
+                background: var(--yj-bg-surface, #212529);
+                color: var(--yj-text-primary, #fff);
+            }
+
+            /* The box is the whole content, so it gets the whole width
+               rather than the 360px cap it wears in a header. */
+            search-bar {
+                display: block;
+                width: 100%;
+                --yj-search-max-width: none;
+            }
+
+            .hint {
+                margin: 0.75em 0 0;
+                font-size: var(--yj-text-sm, 0.8125rem);
+                color: var(--yj-text-secondary, #b3b3b3);
+            }
+        `,
+    ];
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+        document.addEventListener(OPEN_SEARCH_EVENT, this.open);
+        // Capture, on the host: the path runs document -> host ->
+        // shadow root -> the input inside `search-bar`, so a capture
+        // listener here is the only one that gets the key *before* the
+        // input's own handler. A `@keydown` in the template is a
+        // bubbling listener and would run after the term was cleared,
+        // and there is nowhere to put a `firstUpdated` hook -- the
+        // first render of this element produces no content at all.
+        this.addEventListener('keydown', this.onKeydown, true);
+    }
+
+    override disconnectedCallback(): void {
+        super.disconnectedCallback();
+        document.removeEventListener(OPEN_SEARCH_EVENT, this.open);
+        this.removeEventListener('keydown', this.onKeydown, true);
+    }
+
+    /**
+     * Not a toggle, for `shortcuts-overlay`'s reason: a dialog owns
+     * every unmodified key while it is up, so a second press of the
+     * shortcut that opened it never reaches the shortcut service.
+     */
+    private open = (): void => {
+        if (this.isOpen) return;
+
+        // Nothing to search here is not an error; it is the state the
+        // trigger already declines to render in. Guarding here too is
+        // what makes the keyboard route (Ctrl+F on a phone) agree with
+        // the button.
+        if (!this.searchCtrl.isSearchableView) return;
+
+        this.isOpen = true;
+
+        void this.updateComplete.then(() => {
+            if (this.dialog) this.dialog.open = true;
+
+            // `wa-dialog` positions and shows in its own update, and
+            // `search-bar` populates its own shadow root in one more —
+            // the same lifecycle trap `name-dialog.ts` documents. One
+            // more frame, and the box has an input to focus.
+            requestAnimationFrame(() => this.bar?.focusInput());
+        });
+    };
+
+    private close(): void {
+        if (this.dialog) this.dialog.open = false;
+
+        this.isOpen = false;
+    }
+
+    /**
+     * Escape closes and **keeps the term**; Enter closes and shows the
+     * results.
+     *
+     * Escape is the one worth stating. `search-bar`'s input treats it
+     * as *clear the search*, which is right in a header — the box is on
+     * screen either way, so clearing is the only thing left for the key
+     * to mean. Here it would make dismissing the search surface
+     * silently discard the search, and discarding is what the clear
+     * button inside it is for. So this runs first and closes; the term
+     * survives, and the page behind is still filtered by it.
+     */
+    private onKeydown = (e: KeyboardEvent): void => {
+        if (!this.isOpen) return;
+
+        if (e.key === 'Escape') {
+            e.stopPropagation();
+            this.close();
+
+            return;
+        }
+
+        if (e.key === 'Enter') {
+            e.stopPropagation();
+            e.preventDefault();
+            this.close();
+        }
+    };
+
+    /**
+     * Web Awesome renders `label` into a heading it never points the
+     * `<dialog>` at. See `utils/name-dialog.ts`.
+     */
+    override updated(): void {
+        nameDialogsIn(this.shadowRoot);
+    }
+
+    override render() {
+        if (!this.isOpen) return nothing;
+
+        const scope = this.searchCtrl.scopeLabel;
+
+        return html`
+            <wa-dialog
+                label=${`Search ${scope}`}
+                data-testid="search-dialog"
+                @wa-hide=${() => this.close()}
+            >
+                <search-bar></search-bar>
+                <p class="hint">
+                    Results appear on the page behind this. Press Enter
+                    or close to see them.
+                </p>
+            </wa-dialog>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'search-dialog': SearchDialog;
+    }
+}

frontend/src/components/search-dialog/search-trigger.ts

@@ -0,0 +1,147 @@
+/**
+ * The phone's way into search (#57): one button, in the row that
+ * already says which page you are on.
+ *
+ * **Which views show it is not a decision this component makes.**
+ * `store/search-store.ts` has held the map of what each view searches
+ * since plan 007, and #57's own Findings say so — "that is exactly the
+ * condition for showing the button". So this asks `isSearchableView`
+ * and renders nothing otherwise, and no second list of searchable views
+ * exists to fall out of step with the first.
+ *
+ * **It is an element rather than a `PageAction`**, and that is the
+ * whole reason it is a component at all. Two of the seven searchable
+ * views — `playlist-details` and `smart-playlist-details` — have no
+ * `page-header`; they filter on the term and say so in their own
+ * headers. Declaring search as an action would mean seven hosts each
+ * writing it out, which is the second list again, and it would put a
+ * *phone mode for actions* inside `page-header`, which that component
+ * documents its refusal to grow. An element three headers place is one
+ * statement of the rule, placed three times.
+ *
+ * It does not participate in `page-header`'s overflow measurement, for
+ * the reason the count and the sort control do not: it is 32px, it is
+ * `flex-shrink: 0`, and the header's `fits()` sees its width like any
+ * other child. What it must never do is collapse into the overflow
+ * menu — on a phone that menu is the only home for the page's actions
+ * already, and search would be two taps behind an ellipsis.
+ */
+import { LitElement, css, html, nothing } from 'lit';
+import { customElement, state } from 'lit/decorators.js';
+import '@awesome.me/webawesome/dist/components/icon/icon.js';
+
+import { designTokens } from '../../styles/tokens.css';
+import { PHONE_QUERY } from '@utils/breakpoints';
+import { SearchController } from '@store/controllers/search-controller';
+import { ICON_SEARCH } from '@utils/icon-language';
+import { OPEN_SEARCH_EVENT } from './search-dialog';
+
+@customElement('search-trigger')
+export class SearchTrigger extends LitElement {
+    private searchCtrl = new SearchController(this);
+
+    /**
+     * From `matchMedia` rather than a media query, because this decides
+     * whether the button *exists* — `job-band`'s rule, and for the same
+     * consequence: a header that renders it at every width puts a
+     * second search affordance beside the desktop's own box.
+     */
+    @state() private phone = false;
+
+    private media?: MediaQueryList;
+
+    static override styles = [
+        designTokens,
+        css`
+            :host {
+                display: contents;
+            }
+
+            button {
+                display: inline-flex;
+                align-items: center;
+                justify-content: center;
+                /* The smallest a touch target should be. The header's
+                   own action buttons are smaller because they carry a
+                   label; this one is a glyph. */
+                min-width: 40px;
+                min-height: 40px;
+                padding: 0;
+                background: none;
+                border: 1px solid var(--yj-border-subtle, #555);
+                border-radius: 4px;
+                color: var(--yj-text-primary, #fff);
+                cursor: pointer;
+                flex-shrink: 0;
+            }
+
+            button:focus-visible {
+                outline: 2px solid var(--yj-accent, #ffd43b);
+                outline-offset: -1px;
+            }
+
+            /* A search that is *on* says so without a second control:
+               the page already carries "Showing albums matching ...",
+               and this is the button that reopens the box to change or
+               clear it. */
+            button.filtering {
+                border-color: var(--yj-accent, #ffd43b);
+                color: var(--yj-accent-text, #ffd43b);
+            }
+        `,
+    ];
+
+    override connectedCallback(): void {
+        super.connectedCallback();
+
+        this.media = window.matchMedia(PHONE_QUERY);
+        this.phone = this.media.matches;
+        this.media.addEventListener('change', this.onMedia);
+    }
+
+    override disconnectedCallback(): void {
+        super.disconnectedCallback();
+        this.media?.removeEventListener('change', this.onMedia);
+    }
+
+    private onMedia = (e: MediaQueryListEvent): void => {
+        this.phone = e.matches;
+    };
+
+    private onClick = (): void => {
+        document.dispatchEvent(new CustomEvent(OPEN_SEARCH_EVENT));
+    };
+
+    override render() {
+        if (!this.phone || !this.searchCtrl.isSearchableView) return nothing;
+
+        const scope = this.searchCtrl.scopeLabel;
+        const term = this.searchCtrl.term;
+
+        // The name carries the state, because the colour cannot: a
+        // control that is a different colour and the same word is a
+        // control that says nothing to anyone not seeing it. Same rule
+        // `library-status.ts` states for a partial badge.
+        const label = term
+            ? `Search ${scope}, showing matches for ${term}`
+            : `Search ${scope}`;
+
+        return html`
+            <button
+                data-testid="search-trigger"
+                class=${term ? 'filtering' : ''}
+                aria-label=${label}
+                title=${label}
+                @click=${this.onClick}
+            >
+                <wa-icon name=${ICON_SEARCH}></wa-icon>
+            </button>
+        `;
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'search-trigger': SearchTrigger;
+    }
+}

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

@@ -4,19 +4,10 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { designTokens } from '../../styles/tokens.css';
 
 import type { DragActiveDetail } from '@utils/drag-controller';
-import {
+import { ActiveViewController } from '@store/controllers/active-view-controller';
-    ICON_PLAYLIST,
+import { ViewVisibilityController } from '@store/controllers/view-visibility-controller';
-    ICON_AUTOTAG,
+import { VIEW_META } from '../../services/view-meta';
-    ICON_REQUESTED,
+import type { View } from '../../services/view-meta';
-} from '@utils/icon-language';
-
-type View = 'home' | 'playlists' | 'artists' | 'genres' | 'albums' | 'tracks' | 'explore' | 'downloads' | 'autotag' | 'jobs' | 'settings';
-
-interface NavItem {
-    id: View;
-    label: string;
-    icon: string;
-}
 
 const MIN_WIDTH = 56;
 const MAX_WIDTH = 400;
@@ -159,11 +150,20 @@ export class AppSidebar extends LitElement {
     /** Delay in ms before a drag-hover triggers navigation. */
     private static readonly HOVER_NAV_DELAY = 600;
 
-    /** Home, because that is where `index.ts` now navigates on startup
+    /**
-     *  (H-8). The sidebar does not hear a `navigate` it did not send,
+     * Which item is lit, read from the shell rather than tracked here.
-     *  so this default is what keeps `aria-current` honest on arrival. */
+     *
-    @state()
+     * This used to be a `@state()` field defaulting to `home` -- the
-    private activeView: View = 'home';
+     * landing view -- because "the sidebar does not hear a `navigate`
+     * it did not send". That default was the only honest moment it
+     * ever had: a back-navigation dispatches no `navigate`, so the
+     * highlight stayed on the view the user had just left (#72), and
+     * the copy of this component that `bottom-nav` mounts inside its
+     * drawer opened on `home` from whatever page you were standing on.
+     * The shell publishes the active view now, so there is nothing to
+     * default and nothing to keep in step.
+     */
+    private activeCtrl = new ActiveViewController(this);
 
     @state()
     private isDragging = false;
@@ -200,19 +200,15 @@ export class AppSidebar extends LitElement {
         typeof setTimeout
     > | null = null;
 
-    private navItems: NavItem[] = [
+    /**
-        { id: 'home', label: 'Home', icon: 'house' },
+     * Which destinations the user has kept (#25). The list below is
-        { id: 'playlists', label: 'Playlists', icon: ICON_PLAYLIST },
+     * still the whole set and its order -- this only filters it, and
-        { id: 'artists', label: 'Artists', icon: 'user-group' },
+     * only for drawing: a hidden view is still reachable by `navigate`,
-        { id: 'genres', label: 'Genres', icon: 'masks-theater' },
+     * which is what detail views and the launch page depend on.
-        { id: 'albums', label: 'Albums', icon: 'compact-disc' },
+     */
-        { id: 'tracks', label: 'Tracks', icon: 'music' },
+    private visibilityCtrl = new ViewVisibilityController(this);
-        { id: 'explore', label: 'Explore', icon: 'globe' },
+
-        { id: 'downloads', label: 'Downloads', icon: ICON_REQUESTED },
+    private navItems = VIEW_META;
-        { id: 'autotag', label: 'Autotag', icon: ICON_AUTOTAG },
-        { id: 'jobs', label: 'Jobs', icon: 'list-check' },
-        { id: 'settings', label: 'Settings', icon: 'gear' },
-    ];
 
     override connectedCallback() {
         super.connectedCallback();
@@ -237,10 +233,6 @@ export class AppSidebar extends LitElement {
             'yj-drag-active',
             this.onDragActive as EventListener,
         );
-        document.addEventListener(
-            'navigate',
-            this.onGlobalNavigate as EventListener,
-        );
     }
 
     override disconnectedCallback() {
@@ -262,10 +254,6 @@ export class AppSidebar extends LitElement {
             'yj-drag-active',
             this.onDragActive as EventListener,
         );
-        document.removeEventListener(
-            'navigate',
-            this.onGlobalNavigate as EventListener,
-        );
         this.clearDragHoverTimer();
     }
 
@@ -281,9 +269,12 @@ export class AppSidebar extends LitElement {
             ></div>
             <nav aria-label="Main">
             <ul>
-                ${this.navItems.map((item) => {
+                ${this.navItems
+            .filter((item) => this.visibilityCtrl.visible(item.id))
+            .map((item) => {
+            const active = this.activeCtrl.isActive(item.id);
             const classes = [
-                this.activeView === item.id
+                active
                     ? 'active'
                     : '',
                 this.dragHoverView === item.id
@@ -299,7 +290,7 @@ export class AppSidebar extends LitElement {
                                 type="button"
                                 class=${classes}
                                 data-testid="nav-${item.id}"
-                                aria-current=${this.activeView === item.id
+                                aria-current=${active
                     ? 'page'
                     : 'false'}
                                 @click=${() =>
@@ -382,19 +373,6 @@ export class AppSidebar extends LitElement {
     private static readonly DROP_VIEWS: Set<View> =
         new Set(['playlists']);
 
-    /** Keeps the highlighted nav item in sync with navigation that
-     * originates outside the sidebar itself (e.g. the launch-page
-     * dispatch in index.ts). */
-    private onGlobalNavigate = (
-        e: CustomEvent<{ view?: string }>,
-    ) => {
-        const view = e.detail.view;
-
-        if (view && this.navItems.some((item) => item.id === view)) {
-            this.activeView = view as View;
-        }
-    };
-
     private onDragActive = (
         e: CustomEvent<DragActiveDetail>,
     ) => {
@@ -460,7 +438,11 @@ export class AppSidebar extends LitElement {
     }
 
     private navigate(view: View) {
-        this.activeView = view;
+        // No optimistic highlight: the shell answers, and it answers
+        // synchronously in `handleNavigate` before it awaits anything.
+        // Setting it here as well is the second opinion this fix
+        // removes -- it is what let a click's highlight survive a
+        // navigation the shell then handled differently.
         this.dispatchEvent(new CustomEvent('navigate', {
             detail: { view },
             bubbles: true,

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

@@ -18,6 +18,7 @@ import { queueStore } from '@store/queue-store';
 import { creditStore } from '@store/credit-store';
 import { PlayerController } from '@store/controllers/player-controller';
 import { SearchController } from '@store/controllers/search-controller';
+import '../search-dialog/search-trigger';
 import { SelectionController } from '@utils/selection-controller';
 import type { SelectionHost } from '@utils/selection-controller';
 import {
@@ -25,7 +26,7 @@ import {
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import {
@@ -39,7 +40,8 @@ import {
 } from '@utils/drag-image';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@lit-labs/virtualizer';
 import type { LitVirtualizer } from '@lit-labs/virtualizer';
@@ -64,6 +66,7 @@ import { list } from '@utils/binding';
 import {
     ICON_PLAYLIST,
     ICON_QUEUE,
+    ICON_SMART_PLAYLIST,
 } from '@utils/icon-language';
 
 
@@ -174,10 +177,10 @@ export class SmartPlaylistDetails
     private dragImageEl: HTMLElement | null = null;
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     @query('track-details')
     private trackDetailsDialog!: TrackDetails;
@@ -186,11 +189,11 @@ export class SmartPlaylistDetails
     // ContextMenuHost interface
     // =================================================================
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -358,6 +361,15 @@ export class SmartPlaylistDetails
             flex-shrink: 0;
         }
 
+        /* #57. Like playlist-details, this view filters on the search
+           term and has no page-header to carry the phone's search
+           button, so the action row does. */
+        .actions-end {
+            margin-left: auto;
+            display: flex;
+            align-items: center;
+        }
+
         .action-button {
             background: none;
             border: 1px solid var(--yj-border-subtle, #555);
@@ -1214,7 +1226,7 @@ export class SmartPlaylistDetails
                     <wa-icon name="arrow-left"></wa-icon>
                 </button>
                 <div class="playlist-avatar">
-                    <wa-icon name="filter"></wa-icon>
+                    <wa-icon name=${ICON_SMART_PLAYLIST}></wa-icon>
                 </div>
                 <div class="playlist-info">
                     <h1
@@ -1299,6 +1311,9 @@ export class SmartPlaylistDetails
                                         Edit Rules
                                     </button>
                                 `}
+                          <div class="actions-end">
+                              <search-trigger></search-trigger>
+                          </div>
                       </div>
                       ${this.editing
                           ? html`
@@ -1451,11 +1466,8 @@ export class SmartPlaylistDetails
 
     private renderContextMenu() {
         return html`
-            <wa-popup
+            <menu-surface
                 id="context-menu"
-                placement="bottom-start"
-                flip
-                shift
                 .active=${this.ctxMenu.contextMenuOpen}
             >
                 ${this.ctxMenu.contextMenuOpen
@@ -1569,13 +1581,12 @@ export class SmartPlaylistDetails
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
 
-            <wa-popup
+            <menu-surface
                 id="playlist-submenu"
+                label="Add to playlist"
                 placement="right-start"
-                flip
-                shift
                 .active=${this.ctxMenu
                     .playlistSubmenuOpen}
             >
@@ -1602,7 +1613,7 @@ export class SmartPlaylistDetails
                           </div>
                       `
                     : nothing}
-            </wa-popup>
+            </menu-surface>
         `;
     }
 }

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

@@ -11,13 +11,14 @@ import {
 import { SelectionController } from '@utils/selection-controller';
 import type { SelectionHost } from '@utils/selection-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
+import { PHONE_QUERY } from '@utils/breakpoints';
 import {
     ContextMenuController,
     contextMenuStyles,
     isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 
-import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import type { ContextMenuHost, MenuTarget } from '@utils/context-menu-controller.js';
 import { PlayerController } from '@store/controllers/player-controller';
 import { SearchController } from '@store/controllers/search-controller';
 import '@components/page-header/page-header';
@@ -62,7 +63,8 @@ import type {
 } from '@lit-labs/virtualizer';
 import { flow } from '@lit-labs/virtualizer/layouts/flow.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
-import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
+import type { MenuSurface } from '../menu-surface/menu-surface';
+import '../menu-surface/menu-surface';
 import '@awesome.me/webawesome/dist/components/dropdown-item/dropdown-item.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { describeError } from '@utils/describe-error';
@@ -105,9 +107,6 @@ const ROW_CHROME_WIDTH =
 const ROW_HEIGHT = 33;
 const PHONE_ROW_HEIGHT = 52;
 
-/** The shell's phone breakpoint, as `index.css` and every component
- *  stylesheet spells it. */
-const PHONE_QUERY = '(max-width: 599px)';
 
 // Inline SVG paths for favorite icons — eliminates wa-icon shadow DOM
 // overhead (30-50 shadow roots during scroll).  Font Awesome 6 paths.
@@ -233,18 +232,18 @@ export class TrackList
     private tracks: library.Track[] = [];
 
     @query('#context-menu')
-    private contextMenuPopup!: WaPopup;
+    private contextMenuPopup!: MenuSurface;
 
     @query('#playlist-submenu')
-    private playlistSubmenuPopup!: WaPopup;
+    private playlistSubmenuPopup!: MenuSurface;
 
     // -- ContextMenuHost interface --
 
-    getContextMenuPopup(): WaPopup | undefined {
+    getContextMenuPopup(): MenuTarget | undefined {
         return this.contextMenuPopup;
     }
 
-    getPlaylistSubmenuPopup(): WaPopup | undefined {
+    getPlaylistSubmenuPopup(): MenuTarget | undefined {
         return this.playlistSubmenuPopup;
     }
 
@@ -2325,11 +2324,8 @@ export class TrackList
             </div>
           `}
 
-      <wa-popup
+      <menu-surface
         id="context-menu"
-        placement="bottom-start"
-        flip
-        shift
         .active=${this.ctxMenu.contextMenuOpen}
       >
         ${this.ctxMenu.contextMenuOpen
@@ -2415,13 +2411,12 @@ export class TrackList
               </div>
             `
                 : nothing}
-      </wa-popup>
+      </menu-surface>
 
-      <wa-popup
+      <menu-surface
         id="playlist-submenu"
+                label="Add to playlist"
         placement="right-start"
-        flip
-        shift
         .active=${this.ctxMenu.playlistSubmenuOpen}
       >
         ${this.ctxMenu.playlistSubmenuOpen && this.selection.hasSelection
@@ -2439,7 +2434,7 @@ export class TrackList
               </div>
             `
                 : nothing}
-      </wa-popup>
+      </menu-surface>
 
       <track-details></track-details>
     `;

frontend/src/icons/names.txt

@@ -19,6 +19,7 @@ regular/heart
 regular/star
 solid/arrow-down-wide-short
 solid/arrow-left
+solid/arrow-right
 solid/arrow-rotate-right
 solid/arrows-rotate
 solid/arrow-up-short-wide
@@ -41,6 +42,7 @@ solid/compact-disc
 solid/copy
 solid/database
 solid/download
+solid/ellipsis
 solid/file-import
 solid/filter
 solid/floppy-disk

frontend/src/services/keyboard-shortcut-service.ts

@@ -16,6 +16,7 @@ import { playerStore } from '@store/player-store';
 import { queueStore } from '@store/queue-store';
 import * as Player from '@go/player/player.js';
 import type { SearchBar } from '@components/search-bar/search-bar';
+import { OPEN_SEARCH_EVENT } from '@components/search-dialog/search-dialog';
 
 // ===================================================================
 // KEY STRING UTILITIES
@@ -387,19 +388,43 @@ async function dispatch(action: string): Promise<void> {
             break;
 
         // Navigation
+        // The key has one meaning -- *let me search this page* -- and
+        // two surfaces since #57. The header box is gone below 600px,
+        // so scoping the query to the bar is not tidiness: an unscoped
+        // `search-bar` also matches the one inside `search-dialog`
+        // while that is open, and would focus a box the user is
+        // already typing in while leaving the phone with nothing at
+        // all. The dialog declines to open on a view with nothing to
+        // search, which is the same condition the trigger renders on.
         case 'nav.search':
         case 'nav.searchAlt': {
             const bar = document.querySelector(
-                'search-bar',
+                'header.top-bar search-bar',
             ) as SearchBar | null;
 
-            if (bar && !bar.hasAttribute('hidden')) {
+            if (bar && bar.checkVisibility()) {
                 bar.focusInput();
+            } else {
+                document.dispatchEvent(new CustomEvent(OPEN_SEARCH_EVENT));
             }
 
             break;
         }
 
+        // The keyboard half of #6. It dispatches the same events the
+        // header's buttons and the detail views' own back buttons do,
+        // rather than calling `history.back()` here: the shell owns the
+        // guard that stops a press at the root leaving the app, and a
+        // second caller reaching for `history` directly is how the old
+        // `navStack` came to disagree with the platform.
+        case 'nav.back':
+            document.dispatchEvent(new CustomEvent('navigate-back'));
+            break;
+
+        case 'nav.forward':
+            document.dispatchEvent(new CustomEvent('navigate-forward'));
+            break;
+
         case 'nav.queue': {
             const queuePanel = document.getElementById(
                 'queue-panel',

frontend/src/services/shortcut-meta.ts

@@ -103,6 +103,18 @@ export const SHORTCUT_META: Record<string, ShortcutMeta> = {
             scope: 'global',
             defaultKey: 'Q',
         },
+        'nav.back': {
+            label: 'Back',
+            category: 'Navigation',
+            scope: 'global',
+            defaultKey: 'Alt+Left',
+        },
+        'nav.forward': {
+            label: 'Forward',
+            category: 'Navigation',
+            scope: 'global',
+            defaultKey: 'Alt+Right',
+        },
         'app.shortcuts': {
             label: 'Keyboard Shortcuts',
             category: 'App',

frontend/src/services/top-bar-fit.ts

@@ -0,0 +1,209 @@
+/**
+ * What the top bar drops when it runs out of room (#143).
+ *
+ * The bar holds five children — the wordmark, back/forward, the library
+ * filter, the search box and the job indicator — and at the bottom of
+ * the Compact band they do not all fit. Measured on `main` at 600×600:
+ * the bar is 611px inside a 600px viewport sitting still, and **862px
+ * while a scan with a long title is running**, because `job-indicator`
+ * is `hidden` when idle and up to 235px wide when it is not. `body` is
+ * `overflow-x: auto`, so what a user sees is a horizontal scrollbar on
+ * a shell that #24 promised would not need one.
+ *
+ * **The fit is measured, never breakpointed**, which is `page-header`'s
+ * rule (#69) and applies here 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 job
+ * indicator by the running job's title, and the search box by its
+ * view-scoped placeholder — so any width you pick is right for exactly
+ * one library, one job and one view. The same sweep that produced the
+ * numbers above found the bar overflowing at every width from 600 to
+ * 899 *and* at 900, where `nav-history` reappears; a breakpoint fixing
+ * "600 to 610" would have fixed the case that happened to be idle.
+ *
+ * **What yields is chosen by #24's own sentence** — *no action is ever
+ * unreachable at any supported size* — which rules out the two cheapest
+ * candidates the issue lists. Hiding the library filter takes away an
+ * action: `library-filter` is the **only** control in the app that sets
+ * the selected library (nothing else calls `setSelectedLibrary`), so
+ * hiding it is trading this promise for the same promise. Collapsing
+ * the search box to an icon is what #57 wants on a phone, but #57 is
+ * blocked behind #62 and building its modal here would be building it
+ * without the thing that blocks it.
+ *
+ * So the two things that yield are the two that are **not** actions and
+ * whose content survives elsewhere:
+ *
+ * 1. **The wordmark**, which is a brand — the window's own title bar
+ *    says the same thing, and #48 wants it down to "YJ" at every width
+ *    anyway. It yields its *width*, not its existence: the rule in
+ *    `index.css` is visually-hidden rather than `display: none`, so the
+ *    document keeps its top-level heading.
+ * 2. **The job indicator's label**, leaving the ring. This is not a new
+ *    judgement — the component already drops it below 600px for exactly
+ *    this reason, and its `sr-only` live region is what announces the
+ *    state either way, so nothing is lost to anyone. What a measurement
+ *    adds is the band between 600 and 900, where whether the label fits
+ *    depends on what else is in the bar rather than on the width alone.
+ *
+ * Measured against the running app with a long-titled scan staged, that
+ * order fits at every width from 320 to 1440 — and collapses nothing at
+ * 320, 390, 599, 899 and 1100, which is the other half of the claim.
+ *
+ * Three things about the mechanism are load-bearing.
+ *
+ * **Every pass starts from all-visible**, so the collapsed set is a
+ * pure function of the current width rather than of how the window got
+ * there. `page-header` states the same rule and the same reasons: a
+ * pass that only ever added would never give the wordmark back, and one
+ * that adjusted by a step would need a hysteresis band to stop it
+ * oscillating on the pixel where it exactly fits.
+ *
+ * **"Fits" is the children against the content box, not `scrollWidth`
+ * against `clientWidth`** — and that distinction is not pedantry, it
+ * is a measured false pass. `scrollWidth` counts a box's *left*
+ * padding and not its right, so with this bar's 2em gutters it
+ * under-reports by 32px: at 700px with a scan running it read
+ * `700/700`, a perfect fit, while `job-indicator` ended 32px past
+ * where the content may go and sat in the gutter. Same family as #69's
+ * title trap, one property over — the measurement that is easiest to
+ * reach for is the one that cannot see the failure. So the predicate
+ * here is the same one `top-bar-fit.spec.ts` asserts: no in-flow child
+ * outside the content box.
+ *
+ * That is only truthful in turn because **nothing here absorbs pressure
+ * by truncating**. The collapsible children are `flex-shrink: 0` in
+ * `index.css`, so a deficit shows up as a child out of bounds instead
+ * of quietly eating the indicator's label, which is `text-overflow:
+ * ellipsis` and would have. The search box is the one child that may
+ * shrink, between its 320px basis and the 200px floor its own
+ * stylesheet sets, and a narrower input hides nothing it was showing.
+ *
+ * **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:
+ * the indicator goes 0 → 235 inside a bar whose width has not changed.
+ * Every element child is observed too.
+ */
+
+/** One thing the bar can give up, cheapest first. */
+interface FitStep {
+    /** For tests and for reading the DOM back. */
+    readonly id: string;
+    /** Applied to the bar; `on` collapses. */
+    readonly collapse: (bar: HTMLElement, on: boolean) => void;
+}
+
+/**
+ * The order things are given up in. Lowest priority first — see the
+ * argument above for why these two and not the library filter.
+ */
+export const FIT_STEPS: readonly FitStep[] = [
+    {
+        id: 'wordmark',
+        collapse: (bar, on) =>
+            bar.querySelector('hgroup')?.classList.toggle('yj-collapsed', on),
+    },
+    {
+        id: 'job-label',
+        collapse: (bar, on) =>
+            bar.querySelector('job-indicator')?.toggleAttribute('compact', on),
+    },
+];
+
+/**
+ * Decide what the bar shows at its current width.
+ *
+ * Exported for the component tier, which can hand it a bar of known
+ * widths; the app installs the observer below and never calls this.
+ *
+ * @returns the ids collapsed, in the order they were given up.
+ */
+export function measureTopBarFit(bar: HTMLElement): string[] {
+    // Below 600px there is no bar to fit (#57): `index.css` takes it
+    // out of the grid and leaves it visually hidden at 1px, carrying
+    // nothing but the document's `h1`. Measuring that reports the
+    // wordmark as overflowing 1px of content box and collapses it every
+    // time -- true, and about nothing, since the whole bar is already
+    // invisible. Asking the *computed position* rather than the
+    // viewport width is what keeps this file free of a breakpoint the
+    // stylesheet already owns.
+    if (getComputedStyle(bar).position === 'absolute') return [];
+
+    const fits = () => {
+        const style = getComputedStyle(bar);
+        const box = bar.getBoundingClientRect();
+        const left = box.left + parseFloat(style.paddingLeft);
+        const right = box.right - parseFloat(style.paddingRight);
+
+        for (const child of bar.children) {
+            const cs = getComputedStyle(child);
+
+            // Out of flow is out of the question: a collapsed wordmark
+            // is absolutely positioned and 1px wide precisely so that
+            // it costs the row nothing.
+            if (cs.display === 'none' || cs.position === 'absolute') continue;
+
+            const r = child.getBoundingClientRect();
+
+            // Sub-pixel slack: a flex row's widths are fractional and a
+            // rounding difference is not an overflow anyone can see.
+            if (r.width > 0 && (r.right > right + 0.5 || r.left < left - 0.5)) {
+                return false;
+            }
+        }
+
+        return true;
+    };
+
+    for (const step of FIT_STEPS) step.collapse(bar, false);
+
+    const collapsed: string[] = [];
+
+    if (!fits()) {
+        for (const step of FIT_STEPS) {
+            step.collapse(bar, true);
+            collapsed.push(step.id);
+
+            if (fits()) break;
+        }
+    }
+
+    return collapsed;
+}
+
+/**
+ * Watch the bar and its children, and keep it fitting.
+ *
+ * Returns the uninstaller, which the tests use; the app installs once
+ * for the life of the session.
+ */
+export function installTopBarFit(bar: HTMLElement): () => void {
+    let measuring = false;
+
+    const measure = () => {
+        // A pass resizes the children it collapses, which the observer
+        // would report back to us. It settles either way — the pass is
+        // idempotent at a given width — but re-entering it is work for
+        // no news, and it is what "ResizeObserver loop completed with
+        // undelivered notifications" is.
+        if (measuring) return;
+
+        measuring = true;
+
+        try {
+            measureTopBarFit(bar);
+        } finally {
+            measuring = false;
+        }
+    };
+
+    const observer = new ResizeObserver(measure);
+
+    observer.observe(bar);
+
+    for (const child of bar.children) observer.observe(child);
+
+    measure();
+
+    return () => observer.disconnect();
+}

frontend/src/services/view-meta.ts

@@ -0,0 +1,64 @@
+import {
+    ICON_PLAYLIST,
+    ICON_AUTOTAG,
+    ICON_REQUESTED,
+} from '@utils/icon-language';
+
+/** A primary destination. Mirrors `backend/config.View`. */
+export type View =
+    | 'home'
+    | 'playlists'
+    | 'artists'
+    | 'genres'
+    | 'albums'
+    | 'tracks'
+    | 'explore'
+    | 'downloads'
+    | 'autotag'
+    | 'settings';
+
+export interface ViewMeta {
+    id: View;
+    label: string;
+    icon: string;
+    /**
+     * Views that are never offered as a toggle. Settings alone, because
+     * a user who hides it cannot get back to unhide it.
+     *
+     * This is the *affordance*; the rule is `backend/config.ViewSpec`'s
+     * `Hideable`, which refuses at the setter and drops the key on load.
+     * `config.toml` is hand-editable, so the checkbox being absent is
+     * not what makes this safe — it is only what stops the question
+     * being asked.
+     */
+    alwaysShown?: boolean;
+}
+
+/**
+ * The app's primary destinations, in the order the navigation draws
+ * them and Settings lists them.
+ *
+ * It is here rather than inside `app-sidebar` because #25 gave it a
+ * second reader: Settings renders a toggle per view and needs the same
+ * labels in the same order. Same shape as `services/shortcut-meta.ts`,
+ * which moved out of `config-page` for the same reason -- a private
+ * static that two surfaces need is a private static that is about to be
+ * copied.
+ *
+ * The labels and icons deliberately do not exist in Go. Which views
+ * exist and what an unconfigured install shows is `backend/config.Views`
+ * and is asked for over the binding; how they are *drawn* is the
+ * frontend's, and lives beside the rest of the icon vocabulary.
+ */
+export const VIEW_META: ViewMeta[] = [
+    { id: 'home', label: 'Home', icon: 'house' },
+    { id: 'playlists', label: 'Playlists', icon: ICON_PLAYLIST },
+    { id: 'artists', label: 'Artists', icon: 'user-group' },
+    { id: 'genres', label: 'Genres', icon: 'masks-theater' },
+    { id: 'albums', label: 'Albums', icon: 'compact-disc' },
+    { id: 'tracks', label: 'Tracks', icon: 'music' },
+    { id: 'explore', label: 'Explore', icon: 'globe' },
+    { id: 'downloads', label: 'Downloads', icon: ICON_REQUESTED },
+    { id: 'autotag', label: 'Autotag', icon: ICON_AUTOTAG },
+    { id: 'settings', label: 'Settings', icon: 'gear', alwaysShown: true },
+];

frontend/src/store/active-view-store.ts

@@ -0,0 +1,90 @@
+/**
+ * Which primary view the app is showing.
+ *
+ * The shell has always known this -- `handleNavigate()` sets
+ * `#main-content`'s `data-active-view` on every path, `_isBack`
+ * included -- and never told anyone. The nav components learned it
+ * from the `navigate` CustomEvent instead, which only the *outbound*
+ * path dispatches: the `popstate` listener calls `handleNavigate()`
+ * directly. So both navs kept highlighting the view you had just left
+ * (#72).
+ *
+ * The fix cannot be a re-dispatch of `navigate`. `index.ts` is itself a
+ * document listener for it, so emitting one from inside
+ * `handleNavigate` is an infinite loop -- and the two statements are
+ * different anyway: `navigate` means *please go to X*, and 28 call
+ * sites across 18 files say it. This says *the active view is now X*,
+ * which only the shell is in a position to say and only once per
+ * navigation.
+ *
+ * Three things about it are load-bearing.
+ *
+ * **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 highlighted
+ * Home -- its `activeView` default, which existed to match the landing
+ * view and matched nothing else ever after. An event has no answer for
+ * a listener that was not there; a value does.
+ *
+ * **A detail view is not a view here.** Opening one leaves the primary
+ * view it was opened from lit, which is what #72 asks for and what
+ * `app-sidebar` used to do by accident -- it guarded on
+ * `navItems.some(...)`, so a name matching no item left its highlight
+ * alone. `bottom-nav` had no such guard and so lit nothing on a detail
+ * view. Neither was correct; the sidebar was stale-but-lucky, and
+ * stating the rule once is what makes the two agree.
+ *
+ * **Whether a view is primary is the shell's fact, not this store's.**
+ * `VIEW_TAGS` in `index.ts` is the list, and a copy of it here is a
+ * second list to forget -- so the caller passes the answer it already
+ * has rather than this file re-deriving it.
+ */
+
+type Subscriber = () => void;
+
+class ActiveViewStore {
+    /** Empty until the shell's first navigation, which happens at
+     *  startup from `GetDefaultPage()`. Nothing is highlighted for that
+     *  moment, which is honest: the alternative is a written-down
+     *  default that is right only when the default page agrees with it. */
+    private activeView = '';
+
+    private subscribers = new Set<Subscriber>();
+
+    /** The active primary view, e.g. `albums`. */
+    get(): string {
+        return this.activeView;
+    }
+
+    isActive(view: string): boolean {
+        return this.activeView !== '' && this.activeView === view;
+    }
+
+    /**
+     * Called by the shell on every navigation, `popstate` included.
+     *
+     * `isPrimary` is `view in VIEW_TAGS` at the call site: a detail
+     * view reports itself and deliberately changes nothing, so the view
+     * it was opened from stays lit until the user picks another one.
+     */
+    setView(view: string, isPrimary: boolean): void {
+        if (!isPrimary) return;
+        if (view === this.activeView) return;
+
+        this.activeView = view;
+        this.notify();
+    }
+
+    subscribe(fn: Subscriber): () => void {
+        this.subscribers.add(fn);
+
+        return () => this.subscribers.delete(fn);
+    }
+
+    private notify(): void {
+        this.subscribers.forEach((fn) => fn());
+    }
+}
+
+export const activeViewStore = new ActiveViewStore();

frontend/src/store/controllers/active-view-controller.ts

@@ -0,0 +1,59 @@
+import type {
+    ReactiveController,
+    ReactiveControllerHost,
+} from 'lit';
+import { activeViewStore } from '../active-view-store';
+
+/**
+ * ActiveViewController connects a Lit component to the
+ * ActiveViewStore.
+ *
+ * Usage in a component:
+ *
+ *   private activeCtrl = new ActiveViewController(this);
+ *
+ *   render() {
+ *     const lit = this.activeCtrl.isActive('albums');
+ *   }
+ *
+ * It reads through to the store rather than copying the value into a
+ * `@state()` field, which is the point of #72: two components holding
+ * their own idea of the active view is what let them disagree with the
+ * shell and with each other.
+ */
+export class ActiveViewController implements ReactiveController {
+    private host: ReactiveControllerHost;
+    private unsubscribe?: () => void;
+
+    constructor(host: ReactiveControllerHost) {
+        this.host = host;
+        host.addController(this);
+    }
+
+    // ===============================================================
+    // LIFECYCLE HOOKS
+    // ===============================================================
+
+    hostConnected(): void {
+        this.unsubscribe = activeViewStore.subscribe(() => {
+            this.host.requestUpdate();
+        });
+    }
+
+    hostDisconnected(): void {
+        this.unsubscribe?.();
+    }
+
+    // ===============================================================
+    // DATA ACCESS
+    // ===============================================================
+
+    /** The active primary view, e.g. `albums`. */
+    get current(): string {
+        return activeViewStore.get();
+    }
+
+    isActive(view: string): boolean {
+        return activeViewStore.isActive(view);
+    }
+}

frontend/src/store/controllers/history-controller.ts

@@ -0,0 +1,40 @@
+import type {
+    ReactiveController,
+    ReactiveControllerHost,
+} from 'lit';
+import { historyStore, type HistoryDepth } from '../history-store';
+
+/**
+ * HistoryController connects a Lit component to the HistoryStore.
+ *
+ * Usage in a component:
+ *
+ *   private historyCtrl = new HistoryController(this);
+ *
+ *   render() {
+ *     const { canBack } = this.historyCtrl.depth;
+ *   }
+ */
+export class HistoryController implements ReactiveController {
+    private host: ReactiveControllerHost;
+    private unsubscribe?: () => void;
+
+    constructor(host: ReactiveControllerHost) {
+        this.host = host;
+        host.addController(this);
+    }
+
+    hostConnected(): void {
+        this.unsubscribe = historyStore.subscribe(() => {
+            this.host.requestUpdate();
+        });
+    }
+
+    hostDisconnected(): void {
+        this.unsubscribe?.();
+    }
+
+    get depth(): HistoryDepth {
+        return historyStore.get();
+    }
+}

frontend/src/store/controllers/view-visibility-controller.ts

@@ -0,0 +1,54 @@
+import type {
+    ReactiveController,
+    ReactiveControllerHost,
+} from 'lit';
+import { viewVisibilityStore } from '../view-visibility-store';
+
+/**
+ * ViewVisibilityController connects a Lit component to the
+ * ViewVisibilityStore.
+ *
+ * It reads through to the store rather than copying the map into a
+ * `@state()` field, for the reason `ActiveViewController` does: there
+ * are two live `<app-sidebar>` instances the moment `bottom-nav`'s
+ * "More" drawer opens, and two components holding their own idea of
+ * which destinations exist is how they come to disagree.
+ */
+export class ViewVisibilityController implements ReactiveController {
+    private host: ReactiveControllerHost;
+    private unsubscribe?: () => void;
+
+    constructor(host: ReactiveControllerHost) {
+        this.host = host;
+        host.addController(this);
+    }
+
+    hostConnected(): void {
+        this.unsubscribe = viewVisibilityStore.subscribe(() => {
+            this.host.requestUpdate();
+        });
+
+        void viewVisibilityStore.init();
+    }
+
+    hostDisconnected(): void {
+        this.unsubscribe?.();
+    }
+
+    /** Whether the navigation should offer this destination. */
+    visible(view: string): boolean {
+        return viewVisibilityStore.visible(view);
+    }
+
+    /**
+     * What the config says, ignoring the download-client gate — the
+     * state Settings' own checkbox shows.
+     */
+    enabled(view: string): boolean {
+        return viewVisibilityStore.enabled(view);
+    }
+
+    setVisible(view: string, visible: boolean): Promise<void> {
+        return viewVisibilityStore.setVisible(view, visible);
+    }
+}

frontend/src/store/download-store.ts

@@ -189,6 +189,8 @@ class DownloadStore {
 
     private initialized = false;
 
+    private providersLoaded = false;
+
     constructor() {
         EventsOn(Events.DownloadProvidersChanged, () => {
             void this.refreshProviders();
@@ -285,6 +287,25 @@ class DownloadStore {
         }
     }
 
+    /**
+     * Loads the providers, and only those, once.
+     *
+     * `init()` additionally fetches the descriptors, the downloads and
+     * the request list, which is right for a page about downloading and
+     * wrong for the sidebar: it only needs `available`, to decide
+     * whether the Downloads destination exists at all (#25), and that
+     * is one query. `DownloadProvidersChanged` keeps it current
+     * afterwards, so configuring a client makes the tab appear without
+     * a restart.
+     */
+    async ensureProviders(): Promise<void> {
+        if (this.providersLoaded) return;
+
+        this.providersLoaded = true;
+
+        await this.refreshProviders();
+    }
+
     async refreshProviders(): Promise<void> {
         try {
             this.providersValue = (await ListProviders()) ?? [];

frontend/src/store/history-store.ts

@@ -0,0 +1,66 @@
+/**
+ * How far the session can go back and forward.
+ *
+ * The History API exposes `length` and nothing useful: it counts
+ * entries the app did not push, does not say where in the list the
+ * current entry is, and `popstate` fires *identically* whether the
+ * user went back or forward. So a control that wants to grey itself
+ * out has to be told, and the shell is the only thing in a position to
+ * know (#6).
+ *
+ * Two rules follow from how the shell counts, and both are the reason
+ * this is a pair of booleans rather than one depth:
+ *
+ * **Forward is not "back, negated".** `pushedEntries` -- the counter
+ * this replaces -- decremented on every `popstate`, which made a
+ * forward navigation look like a second back. The shell keeps an index
+ * per entry and a high-water mark instead, and publishes the two
+ * answers rather than the arithmetic.
+ *
+ * **Back stops at the app's own floor.** The launch entry is
+ * *replaced*, not pushed, so that one back press from the root exits
+ * the app on Android; `canBack` is false there, which is what stops
+ * the header's own button being the thing that quits.
+ */
+
+type Subscriber = () => void;
+
+export interface HistoryDepth {
+    canBack: boolean;
+    canForward: boolean;
+}
+
+class HistoryStore {
+    private depth: HistoryDepth = { canBack: false, canForward: false };
+
+    private subscribers = new Set<Subscriber>();
+
+    get(): HistoryDepth {
+        return this.depth;
+    }
+
+    /** Called by the shell whenever an entry is pushed or restored. */
+    setDepth(canBack: boolean, canForward: boolean): void {
+        if (
+            canBack === this.depth.canBack &&
+            canForward === this.depth.canForward
+        ) {
+            return;
+        }
+
+        this.depth = { canBack, canForward };
+        this.notify();
+    }
+
+    subscribe(fn: Subscriber): () => void {
+        this.subscribers.add(fn);
+
+        return () => this.subscribers.delete(fn);
+    }
+
+    private notify(): void {
+        this.subscribers.forEach((fn) => fn());
+    }
+}
+
+export const historyStore = new HistoryStore();

frontend/src/store/index.ts

@@ -9,6 +9,11 @@ export type { ThemeState, BackgroundShade } from './theme-store';
 export { ThemeController } from './controllers/theme-controller';
 export { searchStore } from './search-store';
 export { SearchController } from './controllers/search-controller';
+export { activeViewStore } from './active-view-store';
+export { ActiveViewController } from './controllers/active-view-controller';
+export { historyStore } from './history-store';
+export type { HistoryDepth } from './history-store';
+export { HistoryController } from './controllers/history-controller';
 export { shortcutsStore } from './shortcuts-store';
 export type { ShortcutsState } from './shortcuts-store';
 export { ShortcutsController } from './controllers/shortcuts-controller';

frontend/src/store/job-store.ts

@@ -30,6 +30,7 @@ export type JobState =
 export type JobKind =
     | 'library-scan'
     | 'index-build'
+    | 'download'
     | 'autotag-apply'
     | 'catalog-enrich';
 

frontend/src/store/view-visibility-store.ts

@@ -0,0 +1,119 @@
+import { EventsOn } from '@runtime/runtime';
+import { GetViewVisibility, SetViewVisible } from '@go/config/config.js';
+import { dictByName } from '@utils/binding';
+import { downloadStore } from './download-store';
+import { Events } from '../events';
+
+type Subscriber = () => void;
+
+/**
+ * Which primary destinations the navigation offers.
+ *
+ * Eleven sidebar entries is more than most libraries need, so #25 makes
+ * them individually toggleable. Three rules about this are load-bearing.
+ *
+ * **Hidden is not unreachable.** This decides what the *nav* draws and
+ * nothing else: `navigate` still resolves a hidden view, which is not a
+ * nicety — detail views navigate into these, and the shell's launch
+ * page is one of them. Nothing here needs a special case for the
+ * highlight either, because #72 moved that onto `active-view-store`:
+ * `app-sidebar` asks `isActive(id)` per *rendered* item, so a hidden
+ * view lights nothing exactly as a detail view does.
+ *
+ * **The defaults live in Go**, in `backend/config.Views`, and this asks
+ * for the *resolved* answer rather than the stored map. A config that
+ * says nothing about a view means "that view's own default", so a copy
+ * of the defaults here would be a second thing to keep in step — and
+ * the one that shipped in the artifact, not the one being edited.
+ *
+ * **Downloads is a second question**, answered by the download client
+ * rather than by the config: a destination for a feature that cannot
+ * work is worse than an absent one. It is gated at `visible()` and not
+ * in the config, so switching it on in Settings still means what it
+ * says once a client exists. `available` is false until the providers
+ * have loaded, which makes the tab *appear* on a fresh launch rather
+ * than appearing and then vanishing — the less jarring half of a race
+ * that resolves in one query.
+ */
+class ViewVisibilityStore {
+    /** The backend's resolved answer, empty until the first load. */
+    private configured: Record<string, boolean> = {};
+
+    private loaded = false;
+
+    private subscribers = new Set<Subscriber>();
+
+    constructor() {
+        EventsOn(Events.GeneralConfigChanged, () => {
+            void this.refresh();
+        });
+
+        // A client configured later has to add the destination without a
+        // restart -- #37's rule, one surface over.
+        downloadStore.subscribe(() => this.notify());
+    }
+
+    /** Loads the visibility map once. Safe to call from every mount. */
+    async init(): Promise<void> {
+        if (this.loaded) return;
+
+        this.loaded = true;
+
+        await Promise.all([
+            this.refresh(),
+            downloadStore.ensureProviders(),
+        ]);
+    }
+
+    /**
+     * Whether the navigation should offer this destination.
+     *
+     * An unknown id is visible: the caller is drawing it from its own
+     * list, and a view this store has not heard of (or has not loaded
+     * yet) is better shown than silently dropped.
+     */
+    visible(view: string): boolean {
+        if (view === 'downloads' && !downloadStore.available) return false;
+
+        return this.configured[view] ?? true;
+    }
+
+    /**
+     * What the *config* says, ignoring the download-client gate — which
+     * is what Settings' own checkbox has to show, or a user with no
+     * client would see Downloads switched off and be unable to switch
+     * it on.
+     */
+    enabled(view: string): boolean {
+        return this.configured[view] ?? true;
+    }
+
+    async setVisible(view: string, visible: boolean): Promise<void> {
+        await SetViewVisible(view, visible);
+
+        // The backend emits GeneralConfigChanged, but the caller is
+        // owed the new state by the time this resolves.
+        await this.refresh();
+    }
+
+    subscribe(fn: Subscriber): () => void {
+        this.subscribers.add(fn);
+
+        return () => this.subscribers.delete(fn);
+    }
+
+    private async refresh(): Promise<void> {
+        try {
+            this.configured = await dictByName(GetViewVisibility());
+            this.notify();
+        } catch (err) {
+            console.error('Failed to load view visibility:', err);
+        }
+    }
+
+    private notify(): void {
+        this.subscribers.forEach((fn) => fn());
+    }
+}
+
+export const viewVisibilityStore = new ViewVisibilityStore();