docs(player): close three of the four gaps with a real device

A Light Phone III (Android 14, SDK 34, arm64, Chrome 113 at 424x439) was attached after the PR was opened, so what it listed as unverifiable was checked rather than left as a caveat. SystemOwnsVolume answers true on the device -- the build tag, the constant, the field and the generated binding, end to end, which is the one thing a source sweep only approximates and which nothing else here compiles at all. The control is absent in both mount points on the real engine, and the transport measures 143px, exactly what the desktop-headless "after" predicted. A stored volume of 37 survives a session that demonstrably rewrote the row. The duck is the one that stays open, and now for a stated reason rather than for want of hardware: the foreground service omits setWillPauseWhenDucked from Oreo, so the framework attenuates us itself and never sends AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -- the device logs `requestAudioFocus() ... flags=0x0` saying so. minSdk is 21, so that path is live code on Android 5.0 to 7.1 and unreachable above it. Asking for a modern phone will not test it.
docs(player): record who owns the volume, and what it gave back
2026-08-21 01:34:44 -04:00 · 2026-08-21 00:53:44 -04:00 · 2026-08-21 00:53:36 -04:00 · 2026-08-21 00:53:21 -04:00 · 2026-08-21 04:14:39 +00:00 · 2026-08-21 00:02:27 -04:00
83 changed files with 8802 additions and 922 deletions
@@ -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
@@ -3732,3 +3732,978 @@ so it is the mechanism and not a test-only door.
 Use the nav item when the *nav* is the subject, and `navigateTo` when
 the view is.
 ## `config-section .header` is ambiguous once a job exists (2026-08-19)
 #27 embeds `<job-panel>` inside four Settings sections, and a panel with
 any job in it also mounts a `job-details-drawer` — whose own header
 carries the class `.header`. So `config-page config-section .header`,
 which `settings-reach.spec.ts` had used since plan 007, resolves to two
 elements and fails Playwright's strict mode the moment a scan has run.
 Two things follow. A spec asserting on a section's *disclosure* should
 locate it by role and name (`getByRole('button', {name: heading})`) or
 scope per section and take `.first()`, not by that class. And this is a
 worked example of the more general trap: a class name is not a
 selector's contract, and a component that embeds another inherits its
 class names into every ancestor query.
 It also only appears in a suite that has *done* something — the
 sections are empty on a fresh app, so this cannot be reproduced by
 opening Settings and looking.
 **And it appears on the second engine, not the first.** CI runs
 chromium then webkit against **one app**, so a spec that scans in the
 chromium pass leaves a finished job the webkit pass then trips over.
 Three specs used that selector; two failed locally and the third
 (`failure-voice.spec.ts`) was green on chromium and red on webkit in
 the same run. Reproducing it locally is running the suite twice against
 one `make dev-headless` — which is worth doing for any change that
 leaves state behind, since it is the only place a cross-engine order
 dependency shows up.
 ## `scrollWidth` counts the left padding and not the right (measured 2026-08-20)
 The obvious predicate for "does this flex row fit" is
 `el.scrollWidth <= el.clientWidth`, and on a box with symmetric gutters
 it **under-reports by one gutter**. `scrollWidth` is the extent of the
 scrollable content area, which includes `padding-left` and excludes
 `padding-right`; `clientWidth` includes both. So a child may end up to
 `padding-right` past where content is allowed to go while the box
 reports a perfect fit.
 Measured on the top bar (`padding: 0 2em`) at 700x600 with a long-titled
 scan staged: `clientWidth 700`, `scrollWidth 700` — and
 `job-indicator`'s right edge at 700 against a content edge of 668, i.e.
 sitting in the whole right gutter. `#143`'s first fix passed its own
 measurement and left the indicator visibly jammed against the window
 edge.
 The predicate `services/top-bar-fit.ts` uses instead is the one its
 spec asserts: no in-flow child's rect outside the parent's *content*
 box, both edges, with half a pixel of slack for fractional flex widths.
 This is the same family as #69's title trap — the measurement easiest to
 reach for is the one that cannot see the failure — and it is worth
 knowing before writing the next one of these: **the fit test and the
 assertion that proves it should be the same test.** It was found only
 because `top-bar-fit.spec.ts` measures per child rather than asserting
 on the container, which is exactly why #69 needed
 `header-action-overflow.spec.ts`.
 ## The top bar's overflow is 11px idle and 262px while working (measured 2026-08-20)
 #143 was filed as "11px at 600x600" and re-measured as 171. Both are the
 same defect seen with different jobs running: `job-indicator` is
 `hidden` when idle, ~144px wide showing "Scanning Music", and **235px**
 showing a real library's scan title ("Scanning Music from the external
 drive"), because the label is capped at 12rem and gets there.
 Swept against the running app with that job staged, `header.top-bar`
 client vs scroll:
 | width | idle | with the long-titled scan |
 |---|---|---|
 | 320, 390, 599 | fits | fits (the phone rules drop the filter and the label) |
 | 600 | 611 | **862** |
 | 700 | fits | 862 |
 | 800 | fits | 862 |
 | 899 | fits | 899 (fits) |
 | 900 | fits | 946 |
 | 1100, 1440 | fits | fits |
 Two things worth keeping. The band is **600–610 idle and 600–900 while
 working**, so "a narrow corner" and "the header is crowded from 900
 down" are both true and the difference is entirely what is in flight —
 which is the case a seeded, settled app can never show you. And 899
 fits while 900 does not, because `nav-history` appears at 900: the worst
 width for the header is not the narrowest one, the same way 900 rather
 than 800 is the worst width for the content area.
 Staging it is `/__test/emit` with a `JobsChanged` snapshot; a job with
 `state: "running"` never completes, so it stays up until an empty
 snapshot is emitted, which is what makes an idle re-measurement look
 like the fix not working.
 ## Two repaint mechanisms, and neither is pinned alone (measured 2026-08-20)
 `CLAUDE.md` already states the rule — *a virtualized list repaints only
 when you tell it to, and the accidental way you were telling it may be
 the thing you are about to delete* — found in `artists-view` and
 `genres-view`. `queue-panel` is a second instance with numbers, and the
 numbers are the part worth keeping.
 It repaints its rows **two** ways:
 - `onSelectionChanged()` calls `virtualizer.requestUpdate()`, which is
  the intended one and the one `track-list` has always had;
 - `.keyFunction=${(track) => track.id}` is a **per-render arrow**, so it
  is a changed property on every host update and repaints the rows by
  itself.
 Removing *either* alone changes nothing observable. That is why #43
 could not be settled by reading the code: the hypothesis in its Findings
 (the repaint is missing) was checkable, false, and would have looked
 identical either way.
 Removing **both** does not break selection either — it delays it. Time
 from click to `aria-selected`, three clicks each:
 | build | ms to highlight |
 |---|---|
 | healthy | 5, 16, 17 |
 | both mechanisms removed | 134, 3,866, 5,816 |
 The highlight arrives on whatever unrelated render happens next (the
 player's 1 Hz position report is the usual candidate). **Four seconds is
 indistinguishable from broken to a user, and invisible to a spec** —
 `expect.poll`'s default 5 s timeout passes the degraded build on every
 assertion. `queue-selection.spec.ts` bounds its selection assertions at
 500 ms for that reason, which is ~30x the healthy case and an order of
 magnitude under the degraded one.
 The general form, for the next spec about anything push-driven: **a poll
 generous enough to be stable is generous enough to miss a latency
 regression entirely.** If "late" is a failure mode worth having, the
 timeout has to say so.
 ## A hit-scan says how much of a row is not selectable (measured 2026-08-20)
 `explore-link` stops the click's propagation on purpose — "the row must
 not also treat it as a selection" — so a click on a track, album or
 artist *name* navigates and selects nothing. That is app-wide and
 deliberate, and the useful question about any given list is how much of
 its row it costs.
 Asking `elementFromPoint` what is under each x across a row, at three
 heights:
 | list | link coverage |
 |---|---|
 | queue panel | 12% |
 | track list | 21% |
 This killed a fix in progress. #43 reads as "selection is broken in the
 queue panel, and fine in the track list", the obvious mechanism is that
 the queue's narrow rows are mostly name, and it is **wrong**: the panel
 is *less* link-covered than the list it is being compared against. The
 scan takes a minute and is worth running before demoting anybody's links
 — `explore-album-details`'s tracklist (number / title / artist /
 duration) is the one that plausibly *is* mostly link, and is the one
 #5 is about to add selection to.
 ## A layout is still moving when a guard says it has arrived (measured 2026-08-20)
 `album-dropdown.spec.ts` failed with `Expected 80, Received 10` twice
 over two sessions, and #133 already strengthened its guard from
 "scrollable at all" to "has at least the range the assertion needs".
 That was necessary and could not be sufficient, and the reason is
 structural rather than a matter of thresholds: **a guard and the write
 it guards are separate CDP round trips**, so the page is free to
 re-lay-out between them. Polling harder cannot close a window between
 two moments; only removing the window can.
 Measured directly, sampling `scrollHeight - clientHeight` on
 `.grid-scroll-container` every frame across a 1440x900 → 900x600 resize,
 three runs:
 | t (ms) | range |
 |---|---|
 | 0 | 0 |
 | 1 | **88** |
 | 8–14 | 330 (settled) |
 88 satisfies a guard asking for 80 and is not the settled value, so the
 guard can pass while the grid is one layout pass from done. Under
 full-suite load the transient is worse — the observed failure had 10 —
 which is why it shows up on the second run of a suite and not in ten
 consecutive runs of the file alone (0/10 both before and after the fix).
 The shape to write instead: **one page-side call that performs the
 action and returns what it observes**, with `expect.poll` retrying
 *that*. `scrollTo()` sets `scrollTop` and returns `scrollTop`, so the
 assertion is about what the grid did rather than about what it was
 ready to do. `layout-overflow.spec.ts`'s sidebar probe already had the
 fused half and was missing the retry; it has both now.
 Worth generalising: a spec that resizes and then measures is asserting
 about a moving target for the next dozen frames. Fuse, then poll.
 ## "The first N tracks" is not a way to ask for an ordinary one (2026-08-20)
 `queue-selection.spec.ts` staged its queue from the first few rows of
 `library.Library.GetTracks(0)` and clicked a track *name*, which
 `explore-link` routes to that track's **album** page. Four tracks in the
 fixture library have no album at all — `01 Tone A`, `02 Tone B`,
 `Title Only`, `no-tags-at-all` — and a name with nothing to route to
 renders as **plain text**, not as a link.
 Two things follow, and the second is the sharper one.
 **The order is the scan's.** `GetTracks` returns `audio_files.id` order,
 i.e. the order the scan inserted rows, which depends on concurrency and
 directory traversal. Locally the first eight are all from two proper
 albums, so the spec passed twice over; CI rebuilds its seed with a real
 scan, got a different eight, and failed on both engines. This is the
 same family as "a seed freezes every default it has already persisted" —
 the fixture library is not a list, it is a *set* with an incidental
 order, and no spec should depend on that order.
 **A loose locator hid it.** The row was located with
 `.locator('.explore-link').first()`, and a row has two — the title and
 the artist. When the title is plain text, `first()` silently resolves to
 the **artist** link, so the click went somewhere real and the assertion
 was about a destination the test had not exercised. `.track-title
 .explore-link` is the locator that says which one it means; the loose
 one turned a fixture problem into a mystery.
 The general rule for this repo's fixture library: it is deliberately
 full of edge cases (untagged, unicode, duplicates, extremes), so a spec
 that wants an *ordinary* track has to **say so** — filter on the
 property it depends on rather than slicing.
 ## A nested rule starting with an element name is dropped on the phone (2026-08-20)
 `CLAUDE.md` records that the device renders in **Chrome 113**, which
 does not have relaxed CSS nesting (Chrome 120). The consequence is
 sharper than "some syntax is unavailable": a nested rule whose selector
 begins with a bare identifier is not a parse error you would notice, it
 is **silently dropped**.
 Three such rules were live in `frontend/index.css`, all inside
 `.bottom-bar`, and all therefore dead on the phone and only on the
 phone:
 ```css
 .bottom-bar {
    #track-info { p { … } }   /* the metadata's ellipsis */
    now-playing { overflow: hidden; }
    audio-player { margin: 0.5em 1em; }
 }
 ```
 The first is the interesting one: it is the *ellipsis* on the bottom
 bar's track title and artist, so on the device that text has never
 truncated — the same class of fault as `now-playing`'s marquee, whose
 `text-overflow` sat on the wrong box and had never produced an ellipsis
 in any mode. Both are invisible to every assertion and visible in a
 screenshot.
 `& p`, `& now-playing`, `& audio-player` are valid in both, so the fix
 is one character per rule. What is worth keeping is the rule of thumb:
 **inside a nested block, always write `&`** — and note that a rule
 inside `@media` is *not* nested, so `@media … { bottom-nav { … } }`
 elsewhere in that file is fine and needs nothing.
 `make css-check` does not catch this (it looks for backticks that end a
 tagged template early). Filed as an issue: the check is the natural
 place for it, being the same shape of trap — a silent, phone-only,
 screenshot-only failure.
 ## Centring a bar costs the control in the middle of it (measured 2026-08-20)
 #23 asks for the transport centred in the bottom bar. The obvious
 implementation — make the outer two grid tracks the same width, so the
 middle is centred by construction — is right, and the first cut of it
 was a regression, because "the same width" was taken to mean *the
 metadata's* width on both sides.
 Measured at 800px, with the seek bar's own track:
 | layout | seek track | transport column |
 |---|---|---|
 | `320px 1fr auto` (before) | 257 | 407 |
 | both sides `--now-playing-width` | **61** | 179 |
 | both sides `min(--now-playing-width, 25%)` | 246 | 364 |
 At 200% text the middle row is worse still: 130 before, **0** with the
 uncapped sides. Centring is free at 1440 and expensive at 800, so a
 change checked only at a comfortable width looks perfect.
 The general form: **a symmetric layout reserves space on the side that
 does not need it.** The right-hand group here is ~141px (volume plus
 the queue button) and was being given 320 to keep the arithmetic
 symmetric. Cap the side tracks against the *bar*, not against their
 content, and the middle gets the difference.
 The spec that pins this is two assertions, not one, and that split is
 deliberate: an uncapped build is *perfectly centred* and fails only the
 seek-bar width, so a spec asserting centring alone would have passed
 the regression.
 ## The phone's way into Now Playing was under the artwork (measured 2026-08-20)
 `phone-shell.spec.ts`'s "opens the full-screen now playing" failed in CI
 on both engines, three times across two branches that could not have
 caused it, and passed on re-run each time. It was filed as a flake
 (#150). It is not one: **it depends on which track is playing.**
 `.expand` — the phone's only route into `<now-playing-view>` — is
 `position: absolute; inset: 0` inside `.cover-art-wrapper`, and
 `.cover-art` is a **later sibling**. Both have `z-index: auto`, so they
 tie on paint order and the later one wins. With an `<img>` that costs
 nothing; with no artwork the placeholder `wa-icon` renders and takes
 every click aimed at the button underneath it.
 Measured at 390px with `elementFromPoint` at the button's centre:
 | playing track | hit test |
 |---|---|
 | has artwork | `button.expand` |
 | no artwork | **`wa-icon`** |
 | no artwork, with `z-index: 1` | `button.expand` |
 So on a phone, the only way into the full-screen player stopped working
 whenever the current song had no cover — and this has nothing to do with
 the fixture: any library has untagged files.
 Three things worth keeping.
 **"Flaky in CI" was the wrong diagnosis and it cost three cycles.** The
 spec starts the *first* row of the track list, so which track it plays
 is the order the scan inserted rows in — the same root cause as #156,
 one spec over. A test whose subject is a hit test has to *choose* the
 case that breaks it.
 **The first two hypotheses were both wrong, and both were plausible.**
 A custom element's upgrade replacing its own contents, and the cover
 preview's `mouseenter` opening a popup under the pointer. Neither
 survived contact with `elementFromPoint`, which took a minute and would
 have saved the other two cycles.
 **And the spec that pins it needs the 90-second track**, because a
 2-second one finishes before the assertions run — the trap
 `fixtures.ts` already documents. Note the filter that does *not* work:
 `library.Track.CoverArt` is empty for all 31 fixture rows, so "the
 first track with no cover art" selects nothing in particular. The
 placeholder's presence is asserted instead, which is the property the
 test actually depends on.
 ## An activity recreation kills the process, deterministically (measured 2026-08-20)
 #52's report was "sometimes crashes or restarts when reopened after
 running in the background". Measured on a real device, the *fault* is
 not intermittent at all — only its trigger is.
 Device: Light Phone III (TLP301), Android 14 / SDK 34, arm64-v8a,
 WebView **Chrome 113** at 424x439 CSS px. Debug build
 (`app.yellowjacket.dev`), installed beside the released `v0.3.1` with
 `install -r`.
 **Conditional on the activity actually being recreated in a live
 process, the process died 8 times out of 8** — 3 by hand, then 5/5 in a
 scripted loop. The runs where it survived were runs where no recreation
 happened (one `Wails bridge initialized` in the log rather than two), so
 they are inconclusive rather than passes; a harness that does not check
 for the second init reports those as green and reads as flakiness.
 After the fix: 5/5 recreations survived, plus 6 background/foreground
 cycles and 3 interleaved recreations on one pid.
 The mechanism is three log lines:
 ```
 12:47:56.159 I/WailsBridge(22956): Wails bridge initialized
 12:48:38.898 I/WailsBridge(22956): Wails bridge initialized   <- same pid
 12:48:39.357 I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
 ```
 `nativeInit` runs `go mainFunc()` on every activity creation; the second
 `main()` reaches `app.Run()`, which refuses because `a.starting` is
 still true behind Android's `select{}`, and `os.Exit(1)` takes the whole
 process — including the healthy first app — with it.
 Four things worth keeping:
 - **`has died: fg  TOP` is not a memory kill.** The system does not
  reclaim the foreground process. This reads as "the OS killed us",
  which is the wrong hypothesis and the reason the issue sat unverified.
 - **There is no crash record of any kind**: `logcat -b crash` empty, no
  `AndroidRuntime`, no `libc: Fatal signal`, no tombstone. `os.Exit` is
  not a crash. The one line that named the fault —
  `slog.Error("application error", "err", ...)`, carrying
  `"application is running or a previous run has failed"` — went to
  `/dev/null`. That is #160.
 - **"Don't keep activities" does not work on this device.**
  `settings put global always_finish_activities 1` reads back as `1`,
  `am set-always-finish-activities` does not exist on this build, and
  the activity was never finished on backgrounding. The report's own
  suggested lever is a dead end here. What *does* work, deterministically
  and in one line, is a configuration change the manifest does not
  declare: `adb shell settings put system font_scale 1.15`
  (`AndroidManifest.xml` declares `orientation|screenSize|
  keyboardHidden|uiMode`, so none of those are triggers).
 - **Surviving is only half the property.** The recreated WebView has to
  still be wired to the running app, which was verified by hooking
  `window._wails.dispatchWailsEvent` and backgrounding/foregrounding:
  `["IndexStatusChanged","JobsChanged","JobsChanged",
  "android:storageAccess"]`. The tempting Java-side fix — making
  `WailsBridge.initialized` static — passes the pid check and fails
  this one, because `nativeInit` is also what re-points the JNI
  reference at the new bridge.
 ## The Taskfile's device tasks uninstall the released app (2026-08-20)
 `android:run:device` builds the **debug** variant
 (`applicationIdSuffix ".dev"`) and then runs
 `adb uninstall {{.APP_ID}}`, where `APP_ID` defaults to
 `app.yellowjacket` — the **release** id. So it deletes the user's
 installed app and its library, installs a different package, and then
 fails to launch the one it removed. `deploy-device` carries the same
 uninstall. Filed as #159; `android-tier.md` had been recommending
 `run:device` as the way onto a device.
 This is the hazard that file already names — "The identity is declared
 twice ... **Nothing enforces that they agree**" — reached by a second
 route: the two ids differ not because someone edited one, but because
 the debug buildType suffixes it.
 ## The uninstall was there to make a bare `install` work (measured 2026-08-20)
 Fixing #159 turned up *why* the `adb uninstall` was in all four tasks,
 which the issue does not say and which decides whether it can simply be
 deleted. The line under it was `adb install`, with **no `-r`** — and
 Android refuses an install over an existing package without it. So the
 uninstall was not a deliberate clean-slate step; it was the price of
 the missing flag, paid on every run, and `install -r` removes the
 reason for it rather than merely removing it.
 That matters because "should the uninstall go at all" looked like a
 trade — drop it and a signing-certificate change fails with
 `INSTALL_FAILED_UPDATE_INCOMPATIBLE` instead of being handled. It is
 not a trade: nothing else was relying on it. The certificate case is
 reported with the command to run, which is what
 `scripts/android-emulator.sh` already did for `make android-install`,
 so this is one existing judgement applied consistently rather than a
 new one.
 ## `wails3 task android:run` installs on a phone (measured 2026-08-20)
 The emulator tasks (`run`, `deploy-emulator`) used a bare `adb install`
 with no `-s`. adb with exactly one device attached uses that device
 whatever kind it is, so with a phone plugged in and no emulator
 running, the task whose summary reads "in the Android Emulator"
 installed on the phone — and, before #159 was fixed, ran
 `adb uninstall app.yellowjacket` against it first. The reported data
 loss was reachable from the *emulator* task, which is not what the
 issue describes and is worse, because nothing in the name warns you.
 Measured after the fix, phone attached and emulator stopped:
 ```
 $ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk --target emulator
 android-deploy: no emulator target is online.
    LP3LHMA531900746	device
    Start one with:  make android-emulator
 ```
 The general form: **a task that names a target has to say so to adb.**
 The device tasks always filtered on `$1 !~ /^emulator-/`; the emulator
 tasks filtered on nothing at all.
 ## The package id can be read back, and costs nothing (2026-08-20)
 `aapt2 dump packagename <apk>` answers in one word and ~40 ms, from
 `$ANDROID_HOME/build-tools/*/aapt2` (versioned, so resolved not
 pinned); `aapt dump badging` is the fallback for older build-tools and
 is what #159's own measurement used. That is cheap enough to do on
 every deploy, which is what makes "the two ids agree by construction"
 affordable rather than aspirational — the alternative considered was
 giving the debug-flavoured tasks `APP_ID` + `.dev`, which is one line
 and leaves the class of bug alive for the next flavour or suffix.
 The guard runs **before** a target is chosen, deliberately: it is a
 question about the artifact, so it can be exercised with nothing
 plugged in, and a build whose id is wrong should be refused whether or
 not there is anything to install it onto. That is what let the negative
 test run safely with the user's phone attached:
 ```
 $ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk \
      --target device --expect app.yellowjacket
 android-pkgid: refusing to act on a package this APK does not declare.
    the APK declares:  app.yellowjacket.dev
    the task expects:  app.yellowjacket
 rc=2
 ```
 That is exactly #159's configuration — debug APK, release id, real
 device — refused with no adb call made.
 ## `make android-emulator`'s boot wait can be satisfied by a phone (2026-08-20)
 Noticed while booting the emulator for #159's verification, with a
 phone also attached. `scripts/android-emulator.sh start` reported
 `waiting for boot ok / android 14` about **eight seconds** after
 launching the emulator, which had not appeared in `adb devices` yet —
 `pick_device`'s last resort is "exactly one device online", and at that
 moment the one online device was the phone. So it waited for the
 phone's boot, found it long since booted, and returned. The emulator
 took another ~10 s to come up.
 Harmless here (the emulator was up before anything used it) and a
 straightforward race otherwise: `start` should wait for a device that
 is an emulator, not for whatever `pick_device` returns. Filed as #162.
 ## The Android runtime transport is not HTTP (measured 2026-08-20)
 Found while trying to drive the phone for #53. `wails3` routes runtime
 calls through `addJavascriptInterface` on Android, not through
 `/wails/runtime` — the WebView cannot deliver a `fetch()` POST body to
 `shouldInterceptRequest`, which the v3 source says in as many words
 (`application_android.go`, "The Android transport"). The runtime
 installs a `customTransport` over `window.wails.invokeAsync(id,
 payload)` and takes the answer on `window._wailsAndroidCallback`.
 Two things follow, and both cost time before the source was read:
 - **`.playwright/init-events.js` does not transfer to the device.** Its
  outbound half hooks `fetch`; a POST to `/wails/runtime` answers
  `Invalid runtime call: missing object value`, which reads like a
  wrong payload shape and is actually the interceptor receiving a URL
  with no body at all. The payload shape was right the whole time. Its
  *inbound* half is still correct, because `dispatchWailsEvent` is the
  entry point in every mode.
 - **Hooking `fetch` from an `eval` is too late on any platform.** The
  bundle captured its reference at module scope, so a wrapper installed
  afterwards records nothing — which is exactly why the harness is an
  `initScript`. Measured: zero calls captured while the app was
  demonstrably making them.
 The working recipe is in `android-tier.md`; it chains the runtime's own
 callback rather than replacing it, so its pending calls still resolve.
 This is what makes the device a tier that can be *driven*.
 ## #53's frontend is byte-identical to the build it was reported against (2026-08-20)
 `git diff v0.3.1 HEAD -- frontend/src/components/audio-player/seekbar/
 frontend/src/store/player-store.ts` is **empty**; the whole diff in that
 area is `backend/player/`. The phone carries the released `v0.3.1`, so
 whatever #53 saw, the component was not what changed — and v0.4.0 is
 where the player audit (#122–#127) landed.
 Measured on that phone, current `main`, with a synthesised 4-minute
 track: the Now Playing seek bar tracks correctly when mounted
 mid-playback (`seekValue` 28 of 240), when the view is opened before
 playback starts, after a tap on the track, and across an activity
 recreation (same pid, bar resumes at 30 → 35). The issue's stated
 symptom did not reproduce in any of them.
 Reverting **only** `backend/player/` to v0.3.1 — the frontend and
 everything else at HEAD — does reproduce a real position defect on the
 same device: six seconds into a 20-second file with no database row,
 played after a 240-second one, the bar read **01:27 of 240**. That is
 #125's stale `trackLengthMs` ("cleared only by UnloadTrack, so a file
 with no row inherited the previous track's duration"), and it is fixed
 at HEAD. Note the *shape* of it: the fraction is roughly right and the
 absolute numbers are wrong, so it presents as a clock that lies rather
 than as a handle that will not move.
 The one-line experiment is worth remembering: v0.3.1's `backend/player`
 compiles against HEAD with a single shim
 (`SetPlaybackFinishedHandler` gained a `srcErr error` parameter), which
 makes "did the backend fix cause this" a ten-minute question instead of
 a full checkout.
 ## An overlay band is not a notification, it is a lid (measured 2026-08-20)
 #62 asks for background jobs to become "a notification" on the phone,
 and the app has exactly one notification surface, so the first version
 of the fix put `<job-panel>` in `notification-host`'s band — which is
 `position: fixed` under the header. It renders correctly, it is on top,
 it is inside the viewport, and it is unusable.
 At the device's 424x439 viewport a **compact** panel showing two active
 jobs is ~216px — half the screen — drawn over the content, with
 `pointer-events: auto` so it swallows every tap underneath. Nothing in
 the component tier could see it. The e2e suite could: four specs failed,
 and *none* of them was about jobs — two `phone-shell` journeys into the
 full-screen Now Playing and `header-action-overflow`'s phone case, all
 three because the band was intercepting taps meant for the app.
 `<job-band>` is in the shell's grid instead, as a row between the top
 bar and the main panel, so it **pushes**. That is #24's one sentence
 ("no action is ever unreachable at any supported size") deciding a
 layout question: a band that hides the app in order to say the app is
 busy has traded the popover's fault for a worse one.
 Two things fell out of it worth keeping:
 - **A finished row in flow is furniture.** The overlay could afford to
  keep terminal jobs around; a row that holds the content down after
  the work is done cannot. `job-panel` grew `active-only` for the band,
  and Settings keeps finished rows because that is where "did the last
  scan work" is asked.
 - **`job-row` already had the right density.** `variant="compact"` is
  described in its own source as "the popover density", which is
  exactly what the band is replacing — 216px against 259px for the
  same two jobs, and no per-job statistics that a phone has no room
  for.
 ## The e2e suite is the tier that sees a shell regression (2026-08-20)
 Worth stating because it decided how #62 was verified. The change is
 one component, one stylesheet and one line of `index.html`; `make
 ui-test` (955 tests) passed on the broken overlay version and so did
 `tsc`, `lint` and the whole Go suite. The failure was three specs that
 have nothing to do with jobs, failing on `click()` timeouts.
 The corollary for anything that draws over the shell: **run the whole
 e2e suite, not the spec you wrote.** A spec written for a feature
 asserts the feature works; what a new overlay breaks is everything
 else, and only the suite is looking at that.
 ## `contain: paint` is why a Web Awesome popup is clipped on the device (read 2026-08-20, applied 2026-08-21)
 Recorded here because it outlives #57 and #60 both, and because the
 next person to reach for a floating surface will reach for `wa-popup`.
 `wa-popup` renders `<div popover="manual">` and feature-detects the
 Popover API, falling back to `strategy: "fixed"` where there is none.
 The reference device is Chrome 113 and `popover` is Chrome 114, so
 every popup in the app takes the fallback there. `position: fixed`
 escapes ancestor *overflow* but not `contain: paint`, which makes an
 element a containing block for fixed descendants **and clips them** —
 and `index.css` puts `contain: layout style paint` on `.main-panel`
 and on `div.sidebar`.
 So the rule is: **a floating surface opened from inside the main panel
 must be a `wa-dialog`, not a `wa-popup`,** because `<dialog>` /
 `showModal()` is Chrome 37 and uses the real top layer. #57's search
 modal is one on that ground alone; #60 is the same finding applied to
 the six context menus.
 The half that costs time is the second one. **No tier here can
 reproduce the clip.** CI's Chromium and WebKit both have the Popover
 API, so a popup is top-layered and correct, and a spec asserting "the
 surface is not clipped" is green on the broken build. Assert the
 *mechanism* — that there is a native `<dialog>` in the tree at phone
 width — which is the one form of the question a browser here answers
 honestly.
 ## Removing the phone's top bar cost the page header its count (measured 2026-08-21)
 #57 deletes the `top-bar` grid row below 600px and puts a 40px search
 button in `page-header` instead. That button is 43px more than the row
 has at 320px, which is a width the app promises (WCAG 1.4.10 reflow,
 and `header-action-overflow.spec.ts` asks about it).
 Measured on Playlists at 320px, after the fit pass had already
 collapsed all three actions into "More actions" and truncated the title
 to nothing: title 0, count 50, sort 143, search 40, More 38, five 12px
 gaps, 32px of gutters — **363 in 320**, with the More button ending
 27px past the edge. So an *action* was clipped, which is the exact
 defect #69 exists to prevent.
 What yields is the **count**, last, after everything else. It is the
 only item on that row that is neither an identity (the title, which the
 navigation repeats) nor an action (the sort control and the buttons,
 each the only place they are said). With it gone the header is 304 in
 304 and the title even comes back to 19px.
 Two things worth keeping:
 - **The failure was found by the suite, not by the spec.** `make
  ui-test` (964), `tsc` in both packages, `make lint`, `make test` and
  the new `phone-search.spec.ts` were all green; what failed was
  `header-action-overflow.spec.ts` at 320×600, which has nothing to do
  with search. That is #62's lesson holding for a second change in a
  row: anything that adds to or reflows the shell has a blast radius
  the spec you wrote cannot see.
 - **A collapsed thing has to still be in the DOM.** Returning `nothing`
  from `renderCount()` would have taken the count away for the rest of
  the session the first time a 320px window appeared, because
  `measureFit` starts every pass from all-visible and needs a node to
  un-hide. Same shape as the action buttons, which is where the pattern
  was already written down.
 ## The e2e app is long-lived, so a staged job outlives the spec that staged it (measured 2026-08-21)
 `make dev-headless` runs one app across every `make e2e` invocation, and
 `/__test/emit` writes to a store that nothing clears. A first draft of
 `phone-search.spec.ts` asserted the content starts at y=0 with the top
 bar gone; it passed alone and failed in a suite run, because
 `top-bar-fit.spec.ts` had staged a long-titled scan and `<job-band>` is
 a real grid row whenever work is in flight.
 The fix is not `beforeEach` cleanup — it is measuring the right thing:
 the content starts where the **row above it** ends, which is true with a
 job running and without one. An assertion against an absolute
 coordinate was quietly also asserting "and no background job exists",
 which is not something that spec is about or can arrange.
 ## The queue was already the right rectangle; what it lacked was an entry (measured 2026-08-21)
 #55 asks for the queue to be "a real screen instead of a pop-open
 sidebar", and its Direction asks for a `DETAIL_LOADERS` mount. Measured
 against `880adff` at the reference device's real viewport (424x439),
 with #24's overlay open:
 | box | rect |
 |---|---|
 | `.main-panel` | 424 x 318 |
 | `queue-panel` host | 424 x 318 |
 | `.panel-content` | 424 x 318 |
 | `.scrim` | 424 x 318, entirely underneath the panel |
 So a detail-view mount would have drawn the same rectangle in the same
 place. Three things were genuinely missing, and none of them is a
 rendering:
 - **Back navigated the page underneath and left the queue up.** Opened
  on Artists, pressed back: `data-active-view` went `artists` ->
  `albums`, `open` stayed `true`. A press that changes something the
  user cannot see, and costs them their place.
 - **The scrim has zero reachable pixels at phone width**, because
  `panel-content` is `width: 100%` there. #24's tap-outside-to-close
  does not exist on the device.
 - The only pointer route out was a **25x21px** button.
 The rule that followed is that the queue is a *place* exactly while it
 is an overlay and a *control* while it is a column, which reuses #24's
 computed mode rather than adding a breakpoint.
 **The containment finding is the reason the Direction was not
 followed.** Read off the running app rather than the stylesheet:
 | element | computed `contain` |
 |---|---|
 | `queue-panel` (open, overlay) | `layout style` |
 | `.content-area` | `layout style` |
 | `.main-panel` | `content` |
 | `.main-panel > *` (a view) | `content` |
 `queue-panel` has a `wa-popup` context menu, and #60's finding is that
 `position: fixed` escapes overflow but not paint containment on
 Chrome 113. Its ancestry today is paint-free to `body`; a
 `DETAIL_LOADERS` mount would have put it under two paint-containing
 ancestors. **No tier here can see that** — CI's Chromium and WebKit
 both have the Popover API — so the spec asserts the mechanism (the
 panel is not under a paint-contained ancestor) rather than the
 symptom. This is the second change in a row where the honest assertion
 was about where an element *is* rather than how it *looks*.
 One thing worth knowing about the spec: **three of its nine tests fail
 on the build before the change and the other six cannot.** "The entry
 is not orphaned" and "a docked column is not in the stack" are both
 vacuously true of a build that pushes no entry at all. Reverting the
 source and re-running is what established which were which, and the
 file says so in its header rather than implying all nine reproduce.
 ## The phone's transport, and three things that only a screenshot or a stash could see (measured 2026-08-21)
 #59 and #56 were done as one PR — argued on #73 first — because they are
 the same row of pixels: one removes controls from the phone's bar and
 the other enlarges what is left, and both are one property on
 `player-controls`. Measured at 424x439 before:
 | control | before | after |
 |---|---|---|
 | bar: shuffle / prev / play / next / repeat | 33x21 each | prev/next 44, play 56, shuffle+repeat moved |
 | bar: favourite | **18x14** | 44x44 |
 | bar: queue button | 33x29 | gone (#59) |
 | Now Playing: all five | 33x21 each | 44, play 64 |
 | desktop bar: all five | 33x21 | **33x21** |
 Four things cost a cycle each and are worth keeping.
 **A `<button>` does not inherit its font from its parent.** The UA
 stylesheet gives it one, so `font-size: inherit` on a button is a
 *change*, not a no-op: it took every desktop control from 33x21 to
 36x24 by moving them from 13.3px to the shell's 16px. Nothing failed.
 The only way it surfaced was measuring the baseline by stashing the file
 and re-running.
 **And the pixel it was first pinned with was the wrong assertion.** The
 spec asserted the literal `'33x21'`, measured 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
 must not happen is that *we* set something, so that is what it asserts
 now: `min-width` and `min-height` compute to `0px`, and the font-size
 still equals that of a bare `<button>` probed in the same page. That
 form catches the `font-size: inherit` regression in either engine —
 checked by re-introducing it — and it is the same "assert the
 mechanism" move `queue-as-a-screen.spec.ts` makes about containment.
 It is also the second time in two sessions that **CI's WebKit was the
 only tier that could see something**, which is the argument for checking
 that step ran rather than trusting the run's conclusion.
 **A rule at the bottom of `index.css` still loses to a nested rule
 above it.** The phone block is last on purpose because a media query
 adds no specificity — but `#queue-button` is written *nested* inside
 `.bottom-bar`, so it builds to a descendant selector one class more
 specific, and a bare `#queue-button { display: none }` in the phone
 block did nothing at all. Silently: the button simply stayed. Nesting
 adds specificity the source does not show.
 **Removing a control moved the question of how you reach what is left,
 and ten specs were quietly asserting the old answer.** Hiding the bar's
 queue button failed ten tests in four files about the back stack and
 about layout, every one of which opened the queue by clicking
 `#queue-button`. `openTheQueue` in `e2e/support/fixtures.ts` is the
 route *this viewport* offers, and the fix was to stop hard-coding one.
 **And the route it takes did not exist in the state that matters.**
 `now-playing` renders two branches, and the no-track one had no
 `.expand` button — so with nothing loaded there was no way to Now
 Playing, and once the queue button left the bar the queue was
 unreachable outright. The queue is persisted across restarts, so this
 is a state the app launches into, not a corner. It first appeared as a
 *flake* (#168: the long-lived e2e app meant whether a track was loaded
 depended on which spec ran first), which is worth remembering — a leak
 made a deterministic bug look like a race.
 ## Now Playing does not fit a 439px screen, and #56 makes that visible (measured 2026-08-21)
 Two separate things, and only the first is a defect.
 **The art overflowed its own box and drew over the header and the
 title.** It is `width: min(100%, 60vh); aspect-ratio: 1`, so its height
 is derived from its width and bounded by nothing — 60vh bounds the
 *viewport*, not the room left over, and those differ by all the chrome
 above and below. `max-height: 100%` is the fix and shipped with #56.
 Pre-existing: screenshotted on `main`. **Found by reading a screenshot,
 which is the only tier that can see it** — nothing fails, the shell does
 not overflow, and every control is still hittable.
 **With that fixed, the art is a 39px sliver**, because the transport is
 now 172px of a 439px screen. That is a consequence of #56 rather than a
 fault in it, and it is filed as #172 with the per-element budget. #64
 (no in-app volume on Android) is ~30px of pure gain there and #51 is the
 umbrella; folding shuffle and repeat back onto the primary row was
 considered and rejected — it buys 52px, leaves the art at 91px, and
 costs a third arrangement of the same five buttons.
 ## The volume is not ours on Android, and the predicate could not be a width (measured 2026-08-21)
 #64 asked for the in-app volume control to be absent on Android. Its
 first Finding said `volume-control` "already stands down at narrow
 widths", which was true of one of its two copies and is why the issue
 had been read as nearly done. The bar's copy goes by width; the
 full-screen view's copy was deliberately kept, with a comment saying a
 slider does belong there.
 **The crux was platform versus width, and three options were on the
 issue.** What settled it is that the *backend* half of the same issue —
 pin the level at 1.0 — makes a width rule wrong on the platform the
 issue is about: an Android tablet at >=600px gets the bottom bar, and
 the bar's slider would then move a level that is pinned. That is a
 control that cannot act, which `library-status-indicator` already
 settled is worse than none. The same rule is wrong the other way below
 600px, where a narrow desktop window has no hardware keys.
 So the frontend asks the player — `SystemOwnsVolume` — and the answer
 is right at every width in both mount points. **The predicate is named
 after the capability rather than the platform**, which is what makes it
 testable: only `platformOwnsVolume` is behind a build tag, in two files
 that declare nothing else, and everything else is decided against a
 field a Go test sets either way. `frontend/test/components/
 volume-ownership.test.ts` stubs the binding and so exercises the
 *Android* rendering on an ordinary Linux runner; both of its tests were
 confirmed to fail on the build before the change.
 **Measured at 424x439, by flipping `platformOwnsVolume` to true in the
 `!android` file and rebuilding** — the real binding, the real store, the
 real component, everything except the tag:
 | element | before | after |
 |---|---|---|
 | header | 48 | 48 |
 | **album art** | **39** | **68** |
 | title / artist / album | 63 | 63 |
 | transport (seek + controls + volume) | **172** | **143** |
 | — seek bar | 19 | 19 |
 | — player-controls | 116 | 116 |
 | — volume-control | 21 | **0** |
 29px, which is the 21px control plus the 8px flex gap it stops drawing:
 a gap is only painted between boxes, so `:host([hidden])` costs the
 transport nothing rather than leaving a hole. That is #172's "~30px of
 pure gain" confirmed, and the art is 74% larger. It is still the
 second-smallest thing on the screen, which is #51's evidence.
 Three smaller things worth keeping.
 **`:host([hidden])` has to be written down.** The UA's `[hidden]`
 rule is `display: none`, but `volume-control`'s own `:host` sets
 `display: inline-flex` and outranks it — so setting `hidden` alone
 hides nothing. Same family as the nested-`#queue-button` specificity
 trap from the session before.
 **Rendering `nothing` and hiding the host are two different
 assertions**, and the component test makes both: an empty shadow root
 is what stops a by-role or positional query finding a button that
 cannot act, and `hidden` is what stops the host occupying space. Either
 alone passes on a build that gets the other wrong.
 **The bar's centring survives the control going away.** #23's outer
 columns are the same `min()` expression rather than content-sized, so
 at 900px with the volume gone the bar's centre, `audio-player`'s centre
 and `player-controls`' centre are all 450 — checked, because "the
 transport is centred with a slider bolted to one side" is the fault
 that rule exists for and removing the slider is the obvious way to
 re-break it.
 **What no tier here can check**: the constant itself, and ducking
 against a real audio-focus change. The first is a source sweep
 (`TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform`), the second is
 `TestSystemVolumeStillDucks` against the arithmetic. Neither is a
 device, and no device was attached.
 ### The device answered three of the four (measured 2026-08-21, TLP301 / Android 14 / SDK 34 / arm64, Chrome 113 at 424x439)
 A Light Phone III was attached after the PR was opened, so what that PR
 listed as unverifiable was re-checked rather than left as a caveat.
 **The whole chain resolves on the device.** `__yj.call("player.Player.
 SystemOwnsVolume", [])` answers `true` — build tag, `platformOwnsVolume`,
 `Player.systemVolume` and the generated binding, end to end. That is the
 one thing the source sweep only approximates, and it took a real arm64
 device because nothing else here compiles the `android` file at all.
 (`GOOS=android GOARCH=arm64 CGO_ENABLED=1 go build ./backend/...` with
 the NDK's clang compiles it in ~40 s and is worth running first; it
 catches a type error but not a wrong constant.)
 **The control is absent in both mount points**, on the real engine:
 `.bottom-bar volume-control` is `hidden` with an empty shadow root, and
 so is `now-playing-view`'s. Measured on the device, transport **143px**,
 which is the figure the desktop-headless "after" predicted exactly. The
 art is 75px there rather than 68 because the fixture's `.names` block is
 one line shorter, not because anything differs.
 **Nothing persists a level nobody chose, and this is the measurement
 that took some care.** The default (50) surviving proves nothing, since
 50 is also what a fresh row holds. So: force-stop, pull `yj.db`, set
 `player_state.volume = 37`, push it back through
 `run-as … dd` (a `cp` from `/sdcard` is refused — the app sandbox
 cannot read it), relaunch, and drive a queue change to make the row be
 rewritten. Reading it back **the WAL has to be pulled with it** — the
 main file still showed the old `last_track_path` and reads as a write
 that never happened. With `yj.db-wal` beside it: `last_track_path` is
 the new track, so `saveState` ran, and `volume` is still **37**.
 **The duck cannot be verified on this device, and now for a stated
 reason rather than for want of hardware.** `WailsForegroundService`
 builds its `AudioFocusRequest` without `setWillPauseWhenDucked` on
 API >= 26, so the framework attenuates the stream itself and never
 delivers `AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`. The device's own log
 says so: `MediaFocusControl: requestAudioFocus() … AA=USAGE_MEDIA/
 CONTENT_TYPE_MUSIC … req=1 flags=0x0` — no
 `AUDIOFOCUS_FLAG_PAUSES_ON_DUCKABLE_LOSS`. **`minSdk` is 21**, so the
 Go-side duck is not dead code; it is reachable on Android 5.0 to 7.1
 and on nothing newer. Any future "verify ducking on a device" needs one
 of those, and asking for a modern phone will not do it.
 Two smaller things from the same session.
 **A fresh install downloads the real catalog, and it is 209px of the
 screen while it does.** `YJ_CORE_INDEX_URL` is stubbed in
 `dev-headless.sh` and in CI but is real on a device, so the first
 measurement taken was of a screen with `job-band` on it and the art at
 **0px**. That is not a defect and not #172 — it is the environment.
 `explore.Service.StopIndexBuild` and a relaunch is the clean state.
 **The first-run wizard does not dismiss when a library appears by a
 route other than its own** (#175) — it was still up, full-screen and
 intercepting pointer events, after `AddLibrary` succeeded through the
 binding, and was gone after a relaunch. Filed.
@@ -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
@@ -1086,6 +1201,15 @@ 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
@@ -1439,8 +1563,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:
@@ -1481,6 +1605,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
@@ -1527,6 +1883,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
@@ -2187,6 +2598,23 @@ Six things about it are load-bearing:
  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
@@ -2214,6 +2642,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
@@ -666,6 +666,49 @@ 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
@@ -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")
 	}
 }
@@ -54,10 +54,30 @@ type GeneralConfig struct {
 	// 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
 	}
@@ -24,10 +24,25 @@ const (
 	ViewExplore   View = "explore"
 	ViewDownloads View = "downloads"
 	ViewAutotag   View = "autotag"
 	ViewJobs      View = "jobs"
 	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
@@ -73,7 +88,6 @@ var Views = []ViewSpec{
 	{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: ViewJobs, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewSettings, VisibleByDefault: true, Hideable: false, CanLaunch: false},
 }
@@ -66,7 +66,7 @@ func TestViewVisibilityStoredWins(t *testing.T) {
 	general := &GeneralConfig{
 		ViewVisibility: map[string]bool{
 			string(ViewAutotag): true,
-			string(ViewJobs):    false,
+			string(ViewExplore): false,
 		},
 	}
 	general.ApplyDefaults()
@@ -77,8 +77,8 @@ func TestViewVisibilityStoredWins(t *testing.T) {
 		t.Error("autotag was switched on and should be visible")
 	}
-	if resolved[string(ViewJobs)] {
+	if resolved[string(ViewExplore)] {
-		t.Error("jobs was switched off and should be hidden")
+		t.Error("explore was switched off and should be hidden")
 	}
 }
@@ -136,6 +136,58 @@ func TestValidateRevealsAHiddenLaunchPage(t *testing.T) {
 	}
 }
 // 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) {
@@ -213,7 +265,7 @@ func TestViewVisibilityRoundTrips(t *testing.T) {
 		t.Fatalf("SetViewVisible() error: %v", err)
 	}
-	if err := original.SetViewVisible(string(ViewJobs), false); err != nil {
+	if err := original.SetViewVisible(string(ViewExplore), false); err != nil {
 		t.Fatalf("SetViewVisible() error: %v", err)
 	}
@@ -228,8 +280,8 @@ func TestViewVisibilityRoundTrips(t *testing.T) {
 		t.Error("autotag should have loaded as visible")
 	}
-	if resolved[string(ViewJobs)] {
+	if resolved[string(ViewExplore)] {
-		t.Error("jobs should have loaded as hidden")
+		t.Error("explore should have loaded as hidden")
 	}
 }
@@ -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,
 	)
@@ -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
 }
@@ -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
@@ -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
@@ -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])
 		}
 	}
 }
@@ -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)"
@@ -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();
        }
@@ -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) {
@@ -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. */
@@ -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);
  });
 });
@@ -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 }) => {
@@ -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();
@@ -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();
  });
 });
@@ -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);
  });
 });
@@ -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);
    });
  }
 });
@@ -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 };
@@ -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,7 +52,6 @@ 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', () => {
@@ -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();
  });
 });
@@ -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();
  });
 });
@@ -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);
  });
 });
@@ -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);
  });
 });
@@ -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) {
@@ -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!,
    );
  });
 });
@@ -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(
@@ -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 });
  });
 });
@@ -140,6 +140,50 @@ export async function navigateTo(page: Page, view: string): Promise<void> {
    .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) {}
@@ -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.
@@ -207,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.
 */
@@ -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.
 */
@@ -104,6 +104,42 @@ 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
@@ -175,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;
@@ -203,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;
@@ -323,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
@@ -343,46 +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.
       `nav-history` is already gone from 899 down. It would belong
       here anyway and for a stronger reason than width: the phone has
       Back as a gesture or a button the OS owns, and this app hooks it
       (`popstate`), so a second Back in the chrome duplicates a
       control the platform provides. */
    .top-bar library-filter {
        display: none;
    }
    /* 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
@@ -396,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;
@@ -412,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);
    }
 }
@@ -14,6 +14,13 @@
         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>
@@ -30,6 +37,14 @@
        <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>
@@ -40,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
@@ -61,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>
@@ -18,6 +18,9 @@
 //   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';
@@ -25,6 +28,11 @@ 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';
@@ -35,6 +43,11 @@ 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';
@@ -54,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,
@@ -73,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
 // ---------------------------------------------------------------------------
@@ -101,7 +124,6 @@ const VIEW_TAGS: Record<string, string> = {
    explore: 'explore-view',
    autotag: 'autotag-view',
    downloads: 'downloads-view',
    jobs: 'jobs-view',
    settings: 'config-page',
 };
@@ -119,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'),
 };
@@ -316,6 +337,33 @@ window.addEventListener('popstate', (e: PopStateEvent) => {
    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> {
@@ -327,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
@@ -611,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
@@ -635,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'],
    });
@@ -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>
    `;
  }
@@ -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>
    `;
  }
@@ -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;
@@ -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' : ''}"
@@ -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>
@@ -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';
@@ -48,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';
@@ -77,6 +89,24 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
    /** 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);
@@ -101,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
@@ -203,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;
@@ -864,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(),
@@ -896,6 +970,9 @@ export class ConfigPage extends ViewLifecycleMixin(LitElement) {
    }
    protected override onViewDeactivate(): void {
        this.unsubscribeJobs?.();
        this.unsubscribeJobs = null;
        this.cancelLibraryAdded?.();
        this.cancelLibraryRenamed?.();
        this.cancelLibraryRemoved?.();
@@ -905,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(
@@ -1096,6 +1181,114 @@ 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,
@@ -1554,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>
        `;
    }
@@ -1674,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}
@@ -1706,10 +1910,51 @@ 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 ---
    /**
@@ -2161,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"
@@ -2172,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
@@ -2209,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
@@ -2232,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)}
@@ -2275,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>
        `;
    }
@@ -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
@@ -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>
            `;
        }
@@ -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;
    }
 }
@@ -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;
@@ -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;
    }
 }
@@ -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;
    }
 }
@@ -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>
        `;
@@ -188,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 {
@@ -425,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
@@ -11,6 +11,7 @@ import {
    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.
@@ -161,6 +162,15 @@ export class PageHeader extends LitElement {
    @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;
@@ -457,6 +467,20 @@ 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>
@@ -516,12 +540,6 @@ export class PageHeader extends LitElement {
        if (!header) return;
        if (this.actions.length === 0) {
            this.commitCollapsed(new Set());
            return;
        }
        const buttons = new Map<string, HTMLElement>();
        for (const el of this.renderRoot.querySelectorAll<HTMLElement>(
@@ -534,6 +552,7 @@ export class PageHeader extends LitElement {
        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
@@ -555,6 +574,8 @@ export class PageHeader extends LitElement {
        if (more) more.hidden = true;
        if (count) count.hidden = false;
        const collapsed = new Set<string>();
        if (!fits()) {
@@ -571,7 +592,42 @@ export class PageHeader extends LitElement {
            }
        }
-        this.commitCollapsed(collapsed);
+        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. */
@@ -586,7 +642,9 @@ export class PageHeader extends LitElement {
            .map(({ action }) => action);
    }
-    private commitCollapsed(next: Set<string>): void {
+    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));
@@ -754,7 +812,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
        >`;
    }
@@ -27,6 +27,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 {
@@ -1039,6 +1040,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 +1394,9 @@ export class PlaylistDetails
                          `
                        : ''}
                </div>
                <div class="header-end">
                    <search-trigger></search-trigger>
                </div>
            </div>
            ${searchBar}
            <div
@@ -277,6 +277,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();
    }
@@ -390,6 +410,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 {
@@ -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;
        }
@@ -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;
    }
 }
@@ -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;
    }
 }
@@ -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 {
@@ -359,6 +360,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);
@@ -1300,6 +1310,9 @@ export class SmartPlaylistDetails
                                        Edit Rules
                                    </button>
                                `}
                          <div class="actions-end">
                              <search-trigger></search-trigger>
                          </div>
                      </div>
                      ${this.editing
                          ? html`
@@ -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,14 +388,24 @@ 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;
@@ -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();
 }
@@ -15,7 +15,6 @@ export type View =
    | 'explore'
    | 'downloads'
    | 'autotag'
    | 'jobs'
    | 'settings';
 export interface ViewMeta {
@@ -61,6 +60,5 @@ export const VIEW_META: ViewMeta[] = [
    { id: 'explore', label: 'Explore', icon: 'globe' },
    { id: 'downloads', label: 'Downloads', icon: ICON_REQUESTED },
    { id: 'autotag', label: 'Autotag', icon: ICON_AUTOTAG },
    { id: 'jobs', label: 'Jobs', icon: 'list-check' },
    { id: 'settings', label: 'Settings', icon: 'gear', alwaysShown: true },
 ];
@@ -30,6 +30,7 @@ export type JobState =
 export type JobKind =
    | 'library-scan'
    | 'index-build'
    | 'download'
    | 'autotag-apply'
    | 'catalog-enrich';
@@ -0,0 +1,143 @@
 import { EventsOn } from '@runtime/runtime';
 import { GetPopupVolume } from '@go/config/config.js';
 import { SystemOwnsVolume } from '@go/player/player.js';
 import { Events } from '../events';
 type Subscriber = () => void;
 /**
 * Whether the volume control is a click-to-open popup (#42).
 *
 * The popup was the only option, and "click open, drag, click closed"
 * is three gestures for a control a bottom bar has room to just show.
 * So an inline slider is the default and the popup is a setting.
 *
 * **The stored flag names the popup, not the slider**, which is the
 * polarity rule `backend/config` states for every option it has: the
 * zero value has to be the intended answer. An `InlineVolume bool`
 * would default to false, hand the popup to every existing install, and
 * need a migration to say what the default already says.
 *
 * It is a store rather than a field on the component because two
 * components render `<volume-control>` — the bottom bar and the phone's
 * full-screen now-playing view — and a setting that only reached
 * whichever one happened to mount after it changed is the fault
 * `active-view-store` exists to prevent, one surface over.
 *
 * The initial value is the *default* rather than a pending answer, so
 * the first paint is the inline slider and not an empty gap that
 * becomes one. An install that has chosen the popup sees it swap once
 * on load, which is the cheaper of the two wrong first frames: the
 * inline slider occupies the space the popup's button would have.
 *
 * **`available` is the question one step earlier — whether there is a
 * volume of ours to draw at all (#64).** On Android the hardware keys
 * are the volume control and the backend pins its own level at
 * maximum, so a slider here would move nothing.
 *
 * It is asked of the *player* rather than of the viewport, and that is
 * the whole design decision. Every other stand-down rule in this app
 * is a width, because a width is what a browser can answer and what
 * every tier can test — but this one is a property of the build. Keyed
 * on width instead, an Android tablet at 600px or more would draw the
 * bottom bar's slider over a pinned level: a control that cannot act,
 * which `library-status-indicator` settled is worse than none.
 *
 * It lives beside `popup` because both answer "what presentation does
 * the volume control get", both readers are the same two components,
 * and "none" is a presentation. A second store would be a second
 * subscription in the same `connectedCallback` saying the same thing.
 *
 * The initial value is `true` on the same first-frame rule: there is a
 * volume on every platform but one, and the platform that pins it sees
 * the control once at boot and never again in the session — the answer
 * cannot change while the app runs, so by the time the lazily-mounted
 * now-playing view exists it has long been settled by the bar's own
 * copy.
 */
 class VolumeStyleStore {
    private value = false;
    private hasVolume = true;
    private loaded = false;
    private subscribers = new Set<Subscriber>();
    constructor() {
        EventsOn(Events.GeneralConfigChanged, () => {
            void this.refresh();
        });
    }
    /** Whether to draw the popup. Safe to read before `init()`. */
    get popup(): boolean {
        return this.value;
    }
    /**
     * Whether this app has a volume of its own to control. False where
     * the device owns it; see the class comment.
     */
    get available(): boolean {
        return this.hasVolume;
    }
    /** Reads the setting once. Safe to call from every mount. */
    async init(): Promise<void> {
        if (this.loaded) return;
        this.loaded = true;
        await Promise.all([this.refreshAvailability(), this.refresh()]);
    }
    subscribe(fn: Subscriber): () => void {
        this.subscribers.add(fn);
        return () => this.subscribers.delete(fn);
    }
    private async refresh(): Promise<void> {
        try {
            const popup = await GetPopupVolume();
            if (popup === this.value) return;
            this.value = popup;
            this.notify();
        } catch (err) {
            // Nothing to tell the user: the control renders in its
            // default presentation, which is a working volume control.
            console.error('failed to read the volume control setting', err);
        }
    }
    /**
     * Asked once, not on `GeneralConfigChanged`: this is a property of
     * the platform the binary was built for and cannot change while
     * the app is running.
     */
    private async refreshAvailability(): Promise<void> {
        try {
            const owned = await SystemOwnsVolume();
            if (owned === !this.hasVolume) return;
            this.hasVolume = !owned;
            this.notify();
        } catch (err) {
            // The control renders, which is the answer on every
            // platform but one and is the recoverable way to be wrong:
            // a working control nobody needs, rather than a missing one
            // somebody does.
            console.error('failed to ask who owns the volume', err);
        }
    }
    private notify(): void {
        for (const fn of this.subscribers) fn();
    }
 }
 export const volumeStyleStore = new VolumeStyleStore();
@@ -124,6 +124,19 @@ export const ICON_DOWNLOADING = 'download';
 */
 export const ICON_MORE_ACTIONS = 'ellipsis';
 /**
 * Look for something.
 *
 * Deliberately **not** governed by the sweep in
 * `icon-language.test.ts`: `magnifying-glass` has only ever meant this,
 * in the header box and in Explore's own catalog search alike, so
 * governing it would force a rename on two call sites that are already
 * right. It is written down because #57 gave the meaning a *button* as
 * well as a box, and a second surface for the same verb is exactly the
 * point at which two spellings start.
 */
 export const ICON_SEARCH = 'magnifying-glass';
 /**
 * Take this away.
 *
@@ -0,0 +1,54 @@
 /**
 * Opening the queue, from the two buttons that do it.
 *
 * **The queue is a place while it is covering the content, and a
 * control while it sits beside it** (#55). Those are not two components
 * and not two mount points — they are the two presentations #24 already
 * computes, and this is the one line that turns that measurement into a
 * navigation decision.
 *
 * A column is a thing the user docked: back must not undock it, and
 * navigating to Albums must not take it away. An overlay is a screen —
 * at the reference device's 424x439 it is 424x318, which is
 * `.main-panel`'s rect exactly — so it needs the two things a screen
 * has and this one did not: an entry in the back stack, and a way out
 * that answers the platform's own gesture. Measured before this existed:
 * opening the queue on Artists and pressing back moved the page
 * *underneath* to Albums and left the queue up.
 *
 * The mode is read off the panel rather than from a viewport width, for
 * the reason `queue-panel.overlay` is computed at all: the panel is
 * drag-resizable between 200 and 500px and persisted, so a breakpoint
 * is wrong by up to 180px in the direction that hurts.
 */
 export function queuePanelElement(): HTMLElement | null {
    return document.getElementById('queue-panel');
 }
 /** Whether the queue is currently a screen rather than a column. */
 export function queueIsAScreen(): boolean {
    return queuePanelElement()?.hasAttribute('overlay') ?? false;
 }
 /**
 * Show the queue: a navigation where it is a screen, an attribute where
 * it is a column.
 *
 * Both routes end at the same `open` attribute on the same element —
 * `index.ts` handles `navigate {view: 'queue'}` by setting it — because
 * the panel's state is one fact and a second mechanism for it is a
 * second thing to keep in step.
 */
 export function openQueue(): void {
    if (queueIsAScreen()) {
        document.dispatchEvent(new CustomEvent('navigate', {
            bubbles: true,
            composed: true,
            detail: { view: 'queue' },
        }));
        return;
    }
    queuePanelElement()?.setAttribute('open', '');
 }
@@ -63,7 +63,6 @@ describe('<app-sidebar>', () => {
      'nav-explore',
      'nav-downloads',
      'nav-autotag',
      'nav-jobs',
      'nav-settings',
    ]);
  });
@@ -0,0 +1,222 @@
 /**
 * Background work, shown where the work is started (#27).
 *
 * The Jobs tab is gone; each kind's rows now live beside the thing that
 * starts it — scans in Settings → Libraries, index work in Search
 * Index, downloads under the download clients, the autotag apply in the
 * Autotag view. What those four surfaces never had, and what this
 * carries to them, is the *generic* affordances: pause, cancel,
 * "Details", and a finished job you can dismiss.
 *
 * The assertions are about which rows a panel owns and what its buttons
 * do, not about the store — `job-store` already has the snapshot
 * covered, and a panel that renders the right rows for the wrong reason
 * would pass either way.
 */
 import { describe, expect, it, beforeEach } from 'vitest';
 import '@components/jobs/job-panel';
 import { emit, flush, lastArgs, calls, resetHarness, stub } from '@test/support/harness';
 import { Events } from '../../src/events';
 import { fixture, shadow, shadowAll } from '@test/support/render';
 import type { LitElement } from 'lit';
 /** A job snapshot entry, with the fields `job-row` actually reads. */
 const job = (over: Record<string, unknown> = {}) => ({
  id: 'scan:1',
  kind: 'library-scan',
  title: 'Scanning Music',
  state: 'running',
  current: 3,
  total: 10,
  caps: { pausable: true, cancellable: true },
  stages: null,
  stats: null,
  startedAt: Date.now(),
  updatedAt: Date.now(),
  logCount: 0,
  warnCount: 0,
  errorCount: 0,
  ...over,
 });
 /** Push a full snapshot, which is what the backend emits. */
 async function snapshot(jobs: unknown[]): Promise<void> {
  emit(Events.JobsChanged, jobs);
  await flush();
 }
 const rows = (el: HTMLElement) => shadowAll(el, 'job-row');
 const titles = (el: HTMLElement) =>
  rows(el).map((row) => (row as HTMLElement & { job: { title: string } }).job.title);
 describe('<job-panel>', () => {
  beforeEach(async () => {
    resetHarness();
    stub('jobs.Service.GetJobs', []);
    await snapshot([]);
  });
  it('renders only the kinds it was asked for', async () => {
    const el = await fixture<LitElement>('job-panel', {
      kinds: 'index-build,catalog-enrich',
    });
    await snapshot([
      job({ id: 'scan:1', kind: 'library-scan', title: 'Scanning Music' }),
      job({ id: 'idx', kind: 'index-build', title: 'Building the index' }),
      job({ id: 'enrich', kind: 'catalog-enrich', title: 'Filling in artists' }),
    ]);
    await el.updateComplete;
    // The title is inside `job-row`'s own shadow root, so this asks
    // the rows what they are drawing rather than reading the panel's
    // text -- which would pass whether or not a row rendered.
    expect(titles(el)).toEqual(['Building the index', 'Filling in artists']);
  });
  /**
   * #62. The phone's band has no kinds to name: it is standing in for
   * the header indicator, whose whole job was to be the one view of
   * everything at once.
   */
  it('answers for every kind when asked with a star', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: '*' });
    await snapshot([
      job({ id: 'scan:1', kind: 'library-scan', title: 'Scanning Music' }),
      job({ id: 'idx', kind: 'index-build', title: 'Building the index' }),
      job({ id: 'dl:1', kind: 'download', title: 'Downloading Glass Harbour' }),
    ]);
    await el.updateComplete;
    expect(titles(el)).toEqual([
      'Scanning Music',
      'Building the index',
      'Downloading Glass Harbour',
    ]);
  });
  /**
   * The other half of that, and the reason it is a star rather than the
   * meaning of an empty attribute: empty is what a typo and a dropped
   * binding both produce, and "show everything" is the wrong thing to
   * do by accident.
   */
  it('still shows nothing when asked for nothing', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: '' });
    await snapshot([job({ id: 'scan:1', kind: 'library-scan' })]);
    await el.updateComplete;
    expect([el.hidden, rows(el)].map(String)).toEqual(['true', '']);
  });
  /**
   * `full` stays the default so the four settings call sites are
   * untouched; the band asks for the density `job-row` calls "the
   * popover density", because on the phone this panel *is* the popover.
   */
  it('passes its density to the rows, defaulting to full', async () => {
    const settings = await fixture<LitElement>('job-panel', { kinds: '*' });
    await snapshot([job()]);
    await settings.updateComplete;
    const band = await fixture<LitElement>('job-panel', {
      kinds: '*',
      density: 'compact',
    });
    await snapshot([job()]);
    await band.updateComplete;
    expect([
      rows(settings)[0]?.getAttribute('variant'),
      rows(band)[0]?.getAttribute('variant'),
    ]).toEqual(['full', 'compact']);
  });
  /**
   * An idle panel in four places is four pieces of furniture describing
   * an absence — and `hidden` rather than an empty render, because the
   * host's own margin would otherwise still be spent.
   */
  it('takes up no room when it has nothing to say', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: 'download' });
    await snapshot([job({ id: 'scan:1', kind: 'library-scan' })]);
    await el.updateComplete;
    expect(el.hidden).toBe(true);
    expect(rows(el)).toHaveLength(0);
    await snapshot([
      job({ id: 'dl:1', kind: 'download', title: 'Downloading Glass Harbour' }),
    ]);
    await el.updateComplete;
    expect(el.hidden).toBe(false);
    expect(rows(el)).toHaveLength(1);
  });
  /**
   * The controls go through `applyJobControl`, which is what carries
   * the index build's "you will discard hours of downloading"
   * confirmation across this move. A host drawing its own buttons would
   * have dropped it silently.
   */
  it('pauses through the shared handler', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: 'library-scan' });
    await snapshot([job()]);
    await el.updateComplete;
    const row = rows(el)[0]!;
    shadow<HTMLButtonElement>(row, 'button[aria-label^="Pause"]')?.click();
    await flush();
    expect(lastArgs('jobs.Service.PauseJob')).toEqual(['scan:1']);
  });
  /**
   * Cancelling an index build asks first; cancelling a scan does not,
   * because a scan is cheap to re-run. Both answers live in
   * `applyJobControl` and both had to survive the move.
   */
  it('does not ask before cancelling a scan', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: 'library-scan' });
    await snapshot([job()]);
    await el.updateComplete;
    const row = rows(el)[0]!;
    shadow<HTMLButtonElement>(row, 'button[aria-label^="Stop"]')?.click();
    await flush();
    expect(lastArgs('jobs.Service.CancelJob')).toEqual(['scan:1']);
  });
  /**
   * A finished job is dismissed one at a time. There is deliberately no
   * "Clear finished" here: `ClearFinishedJobs` is global, so a Clear in
   * the Libraries panel would discard the index build's history too.
   */
  it('keeps finished jobs, dismissible one by one', async () => {
    const el = await fixture<LitElement>('job-panel', { kinds: 'library-scan' });
    await snapshot([job({ state: 'complete' })]);
    await el.updateComplete;
    const row = rows(el)[0]!;
    shadow<HTMLButtonElement>(row, 'button[aria-label^="Dismiss"]')?.click();
    await flush();
    expect(lastArgs('jobs.Service.DismissJob')).toEqual(['scan:1']);
    expect(calls('jobs.Service.ClearFinishedJobs')).toHaveLength(0);
  });
 });
@@ -49,7 +49,7 @@ describe('<app-sidebar> is reachable', () => {
    const items = shadowAll(el, 'li button');
-    expect(items).toHaveLength(11);
+    expect(items).toHaveLength(10);
    expect(items.every((item) => item.tagName === 'BUTTON')).toBe(true);
  });
@@ -0,0 +1,248 @@
 /**
 * The phone's search surface (#57).
 *
 * Two things are asserted here that the e2e tier cannot reach, and one
 * that it deliberately must not be trusted with.
 *
 * **Which views show the trigger is `search-store`'s answer**, so this
 * walks the map rather than sampling a view: the fault the issue guards
 * against is a second list of searchable views, and a spec that checks
 * Albums checks nothing about Playlists.
 *
 * **The dialog is a `<dialog>`, not a popup.** #60 established from the
 * Web Awesome source that `wa-popup` falls back to `position: fixed`
 * without the Popover API — Chrome 113, the reference device — and that
 * `.main-panel`'s `contain: paint` clips a fixed descendant. Every tier
 * available here has the Popover API, so a popup renders perfectly in
 * CI and is clipped on the device: **an assertion that the surface is
 * not clipped passes on the broken build.** So the assertion is the
 * *mechanism* — a real `<dialog>` in the tree — which is the one form
 * of this that a browser here can answer honestly.
 *
 * The breakpoint is stubbed rather than emulated, for the reason
 * `now-playing-phone.test.ts` gives: the runner's viewport is fixed at
 * 1280x800, and the component reads `matchMedia` in `connectedCallback`
 * precisely so a test can answer it first.
 */
 import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import '@components/search-dialog/search-dialog';
 import '@components/search-dialog/search-trigger';
 import { searchStore } from '@store/search-store';
 import { fixture, shadow, deepShadow } from '@test/support/render';
 import { flush } from '@test/support/harness';
 /** Views the store says can be searched, and what they search. */
 const SEARCHABLE: [string, string][] = [
  ['tracks', 'tracks'],
  ['albums', 'albums'],
  ['artists', 'artists'],
  ['genres', 'genres'],
  ['playlists', 'playlists'],
  ['playlist-details', 'tracks in this playlist'],
  ['smart-playlist-details', 'tracks in this smart playlist'],
 ];
 /** Views with nothing of their own to search, or a search of their own. */
 const UNSEARCHABLE = ['home', 'explore', 'settings', 'downloads', 'autotag'];
 let restoreMedia: (() => void) | null = null;
 /** Answer the shell's phone query with `phone` until restored. */
 function stubPhone(phone: boolean): void {
  const real = window.matchMedia.bind(window);
  window.matchMedia = ((q: string) =>
    q.includes('max-width: 599px')
      ? {
          matches: phone,
          media: q,
          addEventListener() {},
          removeEventListener() {},
        }
      : real(q)) as typeof window.matchMedia;
  restoreMedia = () => {
    window.matchMedia = real;
  };
 }
 beforeEach(() => {
  searchStore.setTerm('');
  searchStore.setCurrentView('tracks');
 });
 afterEach(() => {
  restoreMedia?.();
  restoreMedia = null;
  searchStore.setTerm('');
  searchStore.setCurrentView('tracks');
 });
 describe('<search-trigger>', () => {
  it('is offered on every view the store says can be searched', async () => {
    stubPhone(true);
    // One element, walked across the views: the trigger reads the store
    // on every render, so remounting per view would test mounting
    // rather than the condition.
    const el = await fixture('search-trigger');
    for (const [view] of SEARCHABLE) {
      searchStore.setCurrentView(view);
      await el.updateComplete;
      expect(
        shadow(el, '[data-testid="search-trigger"]'),
        `no trigger on ${view}`,
      ).not.toBeNull();
    }
  });
  it('names what the button will search', async () => {
    stubPhone(true);
    const el = await fixture('search-trigger');
    for (const [view, scope] of SEARCHABLE) {
      searchStore.setCurrentView(view);
      await el.updateComplete;
      expect(
        shadow(el, '[data-testid="search-trigger"]')?.getAttribute(
          'aria-label',
        ),
      ).toBe(`Search ${scope}`);
    }
  });
  it('is absent where there is nothing to search', async () => {
    stubPhone(true);
    const el = await fixture('search-trigger');
    for (const view of UNSEARCHABLE) {
      searchStore.setCurrentView(view);
      await el.updateComplete;
      expect(
        shadow(el, '[data-testid="search-trigger"]'),
        `a trigger appeared on ${view}`,
      ).toBeNull();
    }
  });
  it('is absent above the phone breakpoint, where the header has a box', async () => {
    stubPhone(false);
    const el = await fixture('search-trigger');
    expect(shadow(el, '[data-testid="search-trigger"]')).toBeNull();
  });
  /**
   * A colour is not a signal on its own. The button is the only thing
   * on screen that reopens a filtered search, so the state it is in has
   * to reach someone who cannot see the accent border.
   */
  it('says in its name that a search is applied', async () => {
    stubPhone(true);
    const el = await fixture('search-trigger');
    searchStore.setTerm('aurora');
    await el.updateComplete;
    const button = shadow(el, '[data-testid="search-trigger"]');
    expect(button?.getAttribute('aria-label')).toContain('aurora');
    expect(button?.className).toContain('filtering');
  });
 });
 describe('<search-dialog>', () => {
  it('opens on the event the trigger dispatches, as a real dialog', async () => {
    stubPhone(true);
    const el = await fixture('search-dialog');
    const trigger = await fixture('search-trigger');
    shadow<HTMLElement>(trigger, '[data-testid="search-trigger"]')?.click();
    await flush();
    await el.updateComplete;
    expect(shadow(el, '[data-testid="search-dialog"]')).not.toBeNull();
    // The mechanism, not the appearance: a native <dialog> is what
    // reaches the top layer on Chrome 113, and a wa-popup would look
    // identical in this browser while being clipped on the device.
    expect(deepShadow(el, 'dialog')).not.toBeNull();
  });
  /**
   * It carries the real box rather than a second input, which is what
   * keeps one debounce, one clear button and one view-scoped
   * placeholder — and what keeps `search-store` the only statement of
   * what a view searches.
   */
  it('carries the header search box itself', async () => {
    const el = await fixture('search-dialog');
    document.dispatchEvent(new CustomEvent('open-search'));
    await flush();
    await el.updateComplete;
    expect(shadow(el, 'search-bar')).not.toBeNull();
  });
  /**
   * The one place the shortcut route and the button could disagree.
   * Ctrl+F on a view with nothing to search dispatches the same event
   * the button would, and the button is not there to be pressed.
   */
  it('declines to open where there is nothing to search', async () => {
    const el = await fixture('search-dialog');
    searchStore.setCurrentView('home');
    document.dispatchEvent(new CustomEvent('open-search'));
    await flush();
    await el.updateComplete;
    expect(shadow(el, '[data-testid="search-dialog"]')).toBeNull();
  });
  /**
   * 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 stays on screen either way. Here
   * it would mean dismissing the surface silently discarded the search,
   * and the page behind would refill without being asked to.
   */
  it('keeps the search when it is dismissed', async () => {
    const el = await fixture('search-dialog');
    document.dispatchEvent(new CustomEvent('open-search'));
    await flush();
    await el.updateComplete;
    searchStore.setTerm('aurora');
    const input = deepShadow<HTMLInputElement>(el, 'input');
    expect(input).not.toBeNull();
    input!.dispatchEvent(
      new KeyboardEvent('keydown', {
        key: 'Escape',
        bubbles: true,
        composed: true,
      }),
    );
    await flush();
    await el.updateComplete;
    expect(searchStore.getTerm()).toBe('aurora');
    expect(shadow(el, '[data-testid="search-dialog"]')).toBeNull();
  });
 });
@@ -40,7 +40,7 @@ import '@components/jobs/job-details-drawer';
 import '@components/jobs/job-indicator';
 import '@components/jobs/job-log-view';
 import '@components/jobs/job-row';
-import '@components/jobs/jobs-view';
+import '@components/jobs/job-panel';
 import '@components/library-filter/library-filter';
 import '@components/library-status-indicator/library-status-indicator';
 import '@components/now-playing/now-playing';
@@ -87,8 +87,8 @@ const TAGS = [
  'job-details-drawer',
  'job-indicator',
  'job-log-view',
  'job-panel',
  'job-row',
  'jobs-view',
  'library-filter',
  'library-status-indicator',
  'now-playing',
@@ -0,0 +1,181 @@
 /**
 * The transport in its two contexts (#59, #56).
 *
 * `player-controls` is one component in two places, and what each place
 * wants differs *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 states the context and the viewport states
 * the size band, and this file pins the half a media query cannot
 * express.
 *
 * **What this tier can and cannot see.** It can see which buttons
 * exist, because that is `matchMedia` and a render — and existence is
 * the whole of #59. It cannot see the *sizes*: those come from the
 * context's custom properties, and a component-tier render has no shell
 * around it, so the measurements live in `e2e/specs/phone-transport.spec.ts`
 * where there is a real bar in a real viewport. Asserting a pixel here
 * would be asserting the fallbacks, which is `ui-visual`'s documented
 * blind spot one tier over.
 */
 import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import '@components/audio-player/controls/player-controls';
 import { Events } from '../../src/events';
 import { emit, flush, calls } from '@test/support/harness';
 import { fixture, shadowAll, click } from '@test/support/render';
 /** Reset the backend-owned state the component reads from. */
 function idle(): void {
  emit(Events.TrackChanged, null);
  emit(Events.PlaybackStateChanged, { state: 'stopped' });
  emit(Events.QueueModeChanged, { shuffleMode: false, repeatMode: 'off' });
 }
 const names = (el: Element): Array<string | null> =>
  shadowAll(el, 'button').map((b) => b.getAttribute('aria-label'));
 /**
 * Answer `matchMedia` for the phone query, since the test runner's own
 * window is whatever size the browser provider gives it.
 *
 * It is stubbed rather than resized because what is under test is the
 * component's *reaction* to the answer, and a resize would additionally
 * be asserting that this runner's viewport can get below 600px.
 */
 const realMatchMedia = window.matchMedia;
 function pretendPhone(phone: boolean): void {
  window.matchMedia = ((query: string) => ({
    matches: phone && query.includes('599'),
    media: query,
    addEventListener: () => {},
    removeEventListener: () => {},
  })) as unknown as typeof window.matchMedia;
 }
 afterEach(() => {
  window.matchMedia = realMatchMedia;
 });
 describe('<player-controls> in the bar', () => {
  beforeEach(() => {
    idle();
  });
  it('keeps all five on a desktop, in the order it always had', async () => {
    pretendPhone(false);
    const el = await fixture('player-controls');
    // Unchanged from before #59, deliberately: this is the desktop bar
    // and nothing about it was reported.
    expect(names(el)).toEqual([
      'Shuffle',
      'Previous track',
      'Play',
      'Next track',
      'Repeat: off',
    ]);
  });
  it('draws three on a phone, and does not merely hide the other two', async () => {
    pretendPhone(true);
    const el = await fixture('player-controls');
    expect(names(el)).toEqual(['Previous track', 'Play', 'Next track']);
    // The distinction this asserts is the point. A `display: none`
    // control is still in the shadow root, still something a positional
    // query finds, and still a thing the component claims to have --
    // so "the phone has three controls" would have been true of the
    // pixels and false of the element.
    expect(shadowAll(el, 'button')).toHaveLength(3);
  });
  it('follows the viewport when it changes, not just at construction', async () => {
    pretendPhone(false);
    const el = await fixture('player-controls');
    expect(names(el)).toHaveLength(5);
    // A desktop window dragged narrow is the phone layout, per plan
    // 018's decision 4 -- so this is a real transition and not a
    // hypothetical.
    (el as unknown as { phone: boolean }).phone = true;
    await flush();
    await el.updateComplete;
    expect(names(el)).toEqual(['Previous track', 'Play', 'Next track']);
  });
 });
 describe('<player-controls> full-screen', () => {
  beforeEach(() => {
    idle();
  });
  it('keeps all five on a phone, where the bar keeps three', async () => {
    pretendPhone(true);
    const el = await fixture('player-controls');
    el.setAttribute('context', 'full');
    await el.updateComplete;
    // The same viewport, the other answer: this is why the context is a
    // property and cannot be a media query.
    expect(names(el)).toHaveLength(5);
  });
  it('puts the secondary pair after the primary three, in the DOM', async () => {
    pretendPhone(true);
    const el = await fixture('player-controls');
    el.setAttribute('context', 'full');
    await el.updateComplete;
    // Order, not just membership: the secondary controls are drawn on a
    // second row, and this is asserted in the DOM because visual order
    // and focus order have to agree. A CSS `order` property would move
    // them on screen and leave Tab walking the old sequence.
    expect(names(el)).toEqual([
      'Previous track',
      'Play',
      'Next track',
      'Shuffle',
      'Repeat: off',
    ]);
  });
  it('still routes every button to the backend', async () => {
    pretendPhone(true);
    const el = await fixture('player-controls');
    el.setAttribute('context', 'full');
    await el.updateComplete;
    // Two arrangements, one set of handlers. The regression this
    // guards is the reason a second *component* was refused: a second
    // template renders buttons wired to nothing, which looks perfect
    // in a screenshot and does nothing at all.
    for (const name of [
      'Previous track',
      'Next track',
      'Shuffle',
      'Repeat: off',
    ]) {
      await click(el, `button[aria-label="${name}"]`);
    }
    expect(calls().map((c) => c.path)).toEqual([
      'queue.Queue.Previous',
      'queue.Queue.Next',
      'queue.Queue.ToggleShuffle',
      'queue.Queue.CycleRepeat',
    ]);
  });
 });
@@ -11,7 +11,7 @@ import '@components/audio-player/controls/player-controls';
 import '@components/audio-player/seekbar/seek-bar';
 import '@components/audio-player/volume-control/volume-control';
 import { Events } from '../../src/events';
-import { emit, calls, lastArgs, flush } from '@test/support/harness';
+import { emit, calls, lastArgs, flush, stub } from '@test/support/harness';
 import {
  fixture,
  shadow,
@@ -397,6 +397,111 @@ describe('<seek-bar>', () => {
    expect(lastArgs('player.Player.Seek')).toEqual([42]);
  });
  // #164.  `handleInput` used to call `stopProgress()` and mutate no
  // reactive state, so Lit scheduled no update, `updated()` never ran,
  // and the tail of `updated()` that restarts the interval never
  // executed.  Only a `change` or the next backend report could bring
  // it back -- so an `input` that never commits froze the clock, which
  // on a touch device is an ordinary cancelled gesture.  With no
  // reports arriving, that is permanent.
  it('keeps ticking after a drag that never commits', async () => {
    vi.useFakeTimers();
    const el = await fixture('seek-bar');
    emit(Events.TrackChanged, TRACK);
    emit(Events.PlaybackStateChanged, { state: 'playing' });
    await vi.advanceTimersByTimeAsync(2000);
    await el.updateComplete;
    // A touch lands on the track and is then cancelled: `input`, and
    // no `change` ever follows.
    const slider = shadow<HTMLElement & { value: number }>(el, 'wa-slider');
    if (slider) slider.value = 20;
    slider?.dispatchEvent(new Event('input'));
    await el.updateComplete;
    document.dispatchEvent(new Event('pointerup'));
    await vi.advanceTimersByTimeAsync(0);
    await el.updateComplete;
    await vi.advanceTimersByTimeAsync(3000);
    await el.updateComplete;
    expect(text(el, '[data-testid="elapsed-time"]')).toBe('00:23');
  });
  // The other half of the same fix: while the thumb is held, a report
  // arriving once a second used to overwrite `seekValue` and pull it
  // back out from under the finger.
  it('leaves the thumb where the finger is while a drag is live', async () => {
    vi.useFakeTimers();
    const el = await fixture('seek-bar');
    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 20 });
    emit(Events.PlaybackStateChanged, { state: 'playing' });
    await vi.advanceTimersByTimeAsync(0);
    await el.updateComplete;
    const slider = shadow<HTMLElement & { value: number }>(el, 'wa-slider');
    if (slider) slider.value = 60;
    slider?.dispatchEvent(new Event('input'));
    await el.updateComplete;
    emit(Events.PlaybackPositionChanged, {
      positionSeconds: 4,
      trackLength: 90,
      trackChangeId: 20,
      seq: 7,
      playing: true,
    });
    await vi.advanceTimersByTimeAsync(0);
    await el.updateComplete;
    expect(text(el, '[data-testid="elapsed-time"]')).toBe('01:00');
  });
  // And the drag must not hold the interval hostage once it ends: the
  // report that was skipped mid-drag is not recorded as seen, so the
  // next one is still fresh and is applied.
  it('takes the backend back as the authority once the drag commits', async () => {
    vi.useFakeTimers();
    const el = await fixture('seek-bar');
    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 21 });
    emit(Events.PlaybackStateChanged, { state: 'playing' });
    await vi.advanceTimersByTimeAsync(0);
    await el.updateComplete;
    const slider = shadow<HTMLElement & { value: number }>(el, 'wa-slider');
    if (slider) slider.value = 60;
    slider?.dispatchEvent(new Event('input'));
    await el.updateComplete;
    slider?.dispatchEvent(new Event('change'));
    await el.updateComplete;
    emit(Events.PlaybackPositionChanged, {
      positionSeconds: 61,
      trackLength: 90,
      trackChangeId: 21,
      seq: 9,
      playing: true,
    });
    await vi.advanceTimersByTimeAsync(0);
    await el.updateComplete;
    expect(text(el, '[data-testid="elapsed-time"]')).toBe('01:01');
  });
  it('bounds the slider by the track length', async () => {
    const el = await fixture('seek-bar');
@@ -434,13 +539,40 @@ describe('<seek-bar>', () => {
 * be driven by its own event — watching the volume number, as it used
 * to, meant pressing M visibly did nothing.
 */
 /**
 * The volume control has two presentations (#42), and the icon button
 * means a different thing in each — so both are exercised rather than
 * whichever one happens to be the default.
 *
 * Inline is the default: the slider is simply there, which leaves the
 * icon with nothing to disclose, so it is the mute toggle and is named
 * after that action. In the popup it is a disclosure, so it is named
 * after the *state* it is showing.
 */
 describe('volume control: mute', () => {
-  beforeEach(() => {
+  /**
   * Put the presentation back to the default between tests.
   *
   * `volumeStyleStore` is a singleton whose `init()` reads the setting
   * once, so stubbing the binding inside a test is too late — a
   * previous test has already loaded it. `GeneralConfigChanged` is the
   * store's own refresh trigger and the same one the Settings page
   * fires, so driving it that way exercises the real path instead of
   * reaching for a test-only reset.
   */
  const setPresentation = async (popup: boolean) => {
    stub('config.Config.GetPopupVolume', popup);
    emit(Events.GeneralConfigChanged, {});
    await flush();
  };
  beforeEach(async () => {
    await setPresentation(false);
    emit(Events.VolumeChanged, 40);
    emit(Events.MuteChanged, false);
  });
-  it('shows a muted glyph and label once the backend reports mute', async () => {
+  it('shows a muted glyph once the backend reports mute', async () => {
    const el = await fixture('volume-control');
    expect(shadow(el, 'button')?.getAttribute('data-muted')).toBe('false');
@@ -453,14 +585,53 @@ describe('volume control: mute', () => {
    expect(shadow(el, 'button wa-icon')?.getAttribute('name')).toBe(
      'volume-xmark',
    );
  });
  it('names the inline icon after the action it performs', async () => {
    const el = await fixture('volume-control');
    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe('Mute');
    emit(Events.MuteChanged, true);
    await flush();
    await el.updateComplete;
    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe('Unmute');
  });
  it('names the popup icon after the state it discloses', async () => {
    await setPresentation(true);
    const el = await fixture('volume-control');
    await el.updateComplete;
    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe(
      'Volume 40%',
    );
    emit(Events.MuteChanged, true);
    await flush();
    await el.updateComplete;
    expect(shadow(el, 'button')?.getAttribute('aria-label')).toBe('Muted');
  });
  it('shows the slider without a click when it is inline', async () => {
    const el = await fixture('volume-control');
    // The whole point of the issue: no disclosure to operate first.
    expect(shadow<HTMLInputElement>(el, 'wa-slider')?.value).toBe(40);
  });
  it('keeps showing the volume level while muted, because it is unchanged', async () => {
    await setPresentation(true);
    emit(Events.MuteChanged, true);
    await flush();
    const el = await fixture('volume-control');
    await el.updateComplete;
    await click(el, 'button');
    expect(shadow<HTMLInputElement>(el, 'wa-slider')?.value).toBe(40);
@@ -468,11 +639,24 @@ describe('volume control: mute', () => {
  it('toggles mute through the backend rather than locally', async () => {
    const el = await fixture('volume-control');
    await click(el, 'button');
    expect(calls('player.Player.MuteToggle').length).toBe(1);
    // Nothing optimistic: the icon follows the backend's event.
    expect(shadow(el, 'button')?.getAttribute('data-muted')).toBe('false');
  });
  it('toggles mute from inside the popup, where the icon is a disclosure', async () => {
    await setPresentation(true);
    const el = await fixture('volume-control');
    await el.updateComplete;
    await click(el, 'button');
    await click(el, '.mute-toggle');
    expect(calls('player.Player.MuteToggle').length).toBe(1);
    // Nothing optimistic: the icon follows the backend's event.
    expect(shadow(el, 'button')?.getAttribute('data-muted')).toBe('false');
  });
 });
@@ -27,7 +27,6 @@ import '@components/explore-view/explore-view';
 import '@components/home-view/home-view';
 import '@components/downloads-view/downloads-view';
 import '@components/jobs/jobs-view';
 import '@components/playlist-view/playlist-view';
 import { fixture } from '@test/support/render';
 import { stub, flush } from '@test/support/harness';
@@ -223,7 +222,6 @@ const CACHED_VIEWS = [
  'artists-view',
  'genres-view',
  'downloads-view',
  'jobs-view',
  'playlist-view',
  'explore-view',
  'home-view',
@@ -72,7 +72,6 @@ const ALL_VISIBLE = {
  explore: true,
  downloads: true,
  autotag: true,
  jobs: true,
  settings: true,
 };
@@ -96,7 +95,6 @@ describe('view visibility', () => {
      'explore',
      'downloads',
      'autotag',
      'jobs',
      'settings',
    ]);
  });
@@ -104,11 +102,11 @@ describe('view visibility', () => {
  it('drops the ones the user switched off', async () => {
    const el = await fixture<LitElement>('app-sidebar');
-    await setViews({ ...ALL_VISIBLE, autotag: false, jobs: false });
+    await setViews({ ...ALL_VISIBLE, autotag: false, explore: false });
    await el.updateComplete;
    expect(navIDs(el)).not.toContain('autotag');
-    expect(navIDs(el)).not.toContain('jobs');
+    expect(navIDs(el)).not.toContain('explore');
    expect(navIDs(el)).toContain('settings');
  });
@@ -0,0 +1,93 @@
 /**
 * Who owns the volume, and what the control does when it is not us
 * (#64).
 *
 * **This is the tier that can exercise the Android branch**, and it is
 * the reason the predicate is a backend answer rather than a build tag
 * the frontend cannot see: `SystemOwnsVolume` is a stub here, so the
 * "no volume" rendering is checked on an ordinary Linux CI runner with
 * no device anywhere. What no tier here can check is the *constant*
 * behind it, which `TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform`
 * sweeps the Go source for instead.
 *
 * It is a file of its own because `volumeStyleStore` asks once and
 * latches — the answer is a property of the binary and cannot change
 * while the app runs, so there is deliberately no event that refreshes
 * it. Vitest gives each file its own module registry, which is what
 * lets the stub be in place before the singleton is first touched.
 * The *available* case is the rest of `transport.test.ts`, which mounts
 * the same element under the default stub.
 */
 import { describe, expect, it, beforeEach } from 'vitest';
 import '@components/audio-player/volume-control/volume-control';
 import '@components/now-playing-view/now-playing-view';
 import { Events } from '../../src/events';
 import { emit, resetHarness, stub } from '@test/support/harness';
 import { fixture, shadow, shadowAll } from '@test/support/render';
 import type { TrackInfo } from '@store/player-store';
 const TRACK: TrackInfo = {
  fileName: 'tideline.mp3',
  filePath: '/music/tideline.mp3',
  trackLength: 245,
  seekPosition: 0,
  state: 'playing',
  title: 'Tideline',
  artist: 'Sea Change',
  album: 'Ebb',
  coverArt: '',
  coverArtSmall: '',
  coverArtMedium: '',
  coverArtLarge: '',
  trackChangeId: 1,
  artistMbid: '',
  releaseGroupMbid: '',
  recordingMbid: '',
 };
 describe('a platform whose volume we do not own', () => {
  beforeEach(async () => {
    resetHarness();
    stub('player.Player.SystemOwnsVolume', true);
    stub('config.Config.GetPopupVolume', false);
    // The store latches on the first mount; do it here so every test
    // below sees a settled answer rather than the first frame.
    const warm = await fixture('volume-control');
    await warm.updateComplete;
  });
  it('renders no control at all, and no empty shadow root to find', async () => {
    const el = await fixture('volume-control');
    await el.updateComplete;
    // Both halves matter. An empty shadow root is what stops a
    // positional or by-role query finding a button that cannot act;
    // `hidden` is what stops the host taking a flex item's worth of
    // space in the transport it sits in.
    expect(shadowAll(el, 'button')).toHaveLength(0);
    expect(shadowAll(el, 'wa-slider')).toHaveLength(0);
    expect(el.hidden, 'the host is not hidden').toBe(true);
  });
  it('leaves the rest of the phone transport alone', async () => {
    emit(Events.TrackChanged, TRACK);
    const view = await fixture('now-playing-view');
    await view.updateComplete;
    // Seeking and the transport buttons are not volume, and #64 is
    // allowed to remove one control, not to thin the screen out.
    expect(shadow(view, 'seek-bar')).not.toBeNull();
    expect(shadow(view, 'player-controls')).not.toBeNull();
    const volume = shadow(view, 'volume-control') as HTMLElement | null;
    expect(volume, 'the element is still mounted').not.toBeNull();
    expect(volume!.hidden, 'a mounted volume-control is not hidden').toBe(true);
  });
 });
@@ -0,0 +1,101 @@
 /**
 * Opening the queue is a *navigation* where the queue is a screen, and
 * an *attribute* where it is a column (#55).
 *
 * This is the one decision in that change, so it is pinned at the tier
 * that can state it without a shell: the mode is read off the panel's
 * own `overlay` attribute — which #24 computes from the measured widths
 * — and never from a viewport breakpoint. A breakpoint would silently
 * assume the default 320px panel and be wrong by up to 180px for a user
 * who has dragged it wide, in the direction that hurts.
 *
 * What this tier cannot see is the other half: that the entry is
 * unwound when the panel closes, which lives in the shell's mutation
 * observer. `e2e/specs/queue-as-a-screen.spec.ts` is where that is
 * asserted, and it is asserted as *two* back presses rather than one.
 */
 import { afterEach, describe, expect, it } from 'vitest';
 import { openQueue, queueIsAScreen } from '@utils/open-queue';
 function panel(overlay: boolean): HTMLElement {
    const el = document.createElement('div');
    el.id = 'queue-panel';
    if (overlay) el.setAttribute('overlay', '');
    document.body.appendChild(el);
    return el;
 }
 function recordNavigations(): string[] {
    const seen: string[] = [];
    const listener = (e: Event) => {
        seen.push((e as CustomEvent).detail.view);
    };
    document.addEventListener('navigate', listener);
    cleanup.push(() => document.removeEventListener('navigate', listener));
    return seen;
 }
 const cleanup: Array<() => void> = [];
 afterEach(() => {
    while (cleanup.length) cleanup.pop()!();
    document.getElementById('queue-panel')?.remove();
 });
 describe('opening the queue', () => {
    it('navigates where the queue covers the content', () => {
        const el = panel(true);
        const seen = recordNavigations();
        expect(queueIsAScreen()).toBe(true);
        openQueue();
        expect(seen).toEqual(['queue']);
        // The shell answers the navigation by setting the attribute, so
        // the helper deliberately does *not* set it as well: two
        // mechanisms for one fact is two things to keep in step, which
        // is what `now-playing-view`'s copy of this button was.
        expect(el.hasAttribute('open')).toBe(false);
    });
    it('sets the attribute where the queue is a column', () => {
        const el = panel(false);
        const seen = recordNavigations();
        expect(queueIsAScreen()).toBe(false);
        openQueue();
        // A column is a thing the user docked. Back must not undock it,
        // so it is not a history entry and therefore not a navigation.
        expect(seen).toEqual([]);
        expect(el.hasAttribute('open')).toBe(true);
    });
    it('follows the panel rather than the viewport', () => {
        const el = panel(false);
        const seen = recordNavigations();
        openQueue();
        expect(seen).toEqual([]);
        // Nothing about the window changed; the panel got wider, which
        // is exactly the case a media query cannot express.
        el.removeAttribute('open');
        el.setAttribute('overlay', '');
        openQueue();
        expect(seen).toEqual(['queue']);
    });
    it('says the queue is not a screen when there is no panel at all', () => {
        expect(queueIsAScreen()).toBe(false);
        expect(() => openQueue()).not.toThrow();
    });
 });
@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"os"
 	"strings"
 	"sync/atomic"
 	"github.com/golang-cz/devslog"
 	"github.com/wailsapp/wails/v3/pkg/application"
@@ -28,7 +29,61 @@ var (
 //go:embed all:frontend/dist
 var frontendDistAssets embed.FS
 // mainStarted latches the first entry into main().
 //
 // **On Android main() is called once per *activity*, and the process
 // outlives the activity.** Wails' JNI entry point is
 // `nativeInit`, which does two things: it re-points the native
 // library's global reference at the calling `WailsBridge`, and it runs
 // `go mainFunc()`. `MainActivity.onCreate` calls it, and Android
 // recreates the activity — for a configuration change it does not
 // declare, under memory pressure, or on every single background when
 // the user has "Don't keep activities" switched on — **without
 // restarting the process**.
 //
 // So main() ran again, on a live app, and every path out of that is
 // fatal:
 //
 //   - `application.New` returns the *existing* `globalApplication` when
 //     there is one, silently discarding the second set of Services.
 //   - `app.Run()` then refuses, by design: `a.starting` is still true,
 //     because Android's `platformRun` is `select{}` and never returns.
 //     It answers "application is running or a previous run has failed".
 //   - which lands on `os.Exit(1)` at the foot of this function, and
 //     that takes down the **first**, perfectly healthy app with it —
 //     its database, its queue, and the audio that a foreground service
 //     is holding the process alive to play.
 //
 // ActivityManager then restarts the app, which is the report: "crashes
 // or restarts when reopened after running in the background". It never
 // left a tombstone because `os.Exit` is not a crash, and it never left
 // a log line because an Android app's fd 1 goes to /dev/null.
 //
 // The latch is the whole fix, and it has to be **first**: everything
 // below it — `NewYellowJacketApp` above all, which opens the SQLite
 // database — is work that must not happen twice in one process.
 // Returning early is not a degraded mode: `nativeInit` has already
 // re-attached the bridge, so the recreated activity's WebView talks to
 // the app that is still running, with its queue and its playback
 // position intact. See CLAUDE.md, "An activity is a view onto the
 // process".
 //
 // It is inert off Android, where a process has exactly one main().
 var mainStarted atomic.Bool
 // claimMainOnce reports whether this is the first call to main() in
 // this process. See mainStarted.
 func claimMainOnce() bool {
 	return mainStarted.CompareAndSwap(false, true)
 }
 func main() {
 	// Android calls main() once per activity, and the process outlives
 	// the activity. Nothing below this line may run twice.
 	if !claimMainOnce() {
 		return
 	}
 	// **Mobile has no home directory, and this must run before anything
 	// asks for a path.** backend/system resolves config and data from
 	// $HOME or the OS equivalent, and on Android there is neither: its
@@ -0,0 +1,104 @@
 package main
 import (
 	"go/ast"
 	"go/parser"
 	"go/token"
 	"testing"
 )
 // TestMainRunsOncePerProcess pins the latch itself.
 func TestMainRunsOncePerProcess(t *testing.T) {
 	t.Parallel()
 	mainStarted.Store(false)
 	if !claimMainOnce() {
 		t.Fatal("the first call to claimMainOnce must claim it")
 	}
 	if claimMainOnce() {
 		t.Fatal("a second call to claimMainOnce must not claim it: " +
 			"on Android that second call is a second main() in a live " +
 			"process, and every path out of it ends in os.Exit(1)")
 	}
 }
 // TestMainClaimsBeforeItDoesAnything is the assertion that actually
 // guards #52, and it is a source sweep for the reason
 // TestNoDirectRuntimeEmits is: no tier here runs main() on Android, so
 // nothing else can see work creeping in above the latch.
 //
 // The failure it exists for is not the latch being deleted — that is
 // loud. It is a line being added above it: a second
 // NewYellowJacketApp opens the SQLite database a second time in one
 // process, and it would do so on every activity recreation, silently,
 // on a build that otherwise looks entirely healthy.
 func TestMainClaimsBeforeItDoesAnything(t *testing.T) {
 	t.Parallel()
 	fset := token.NewFileSet()
 	file, err := parser.ParseFile(fset, "main.go", nil, 0)
 	if err != nil {
 		t.Fatalf("parse main.go: %v", err)
 	}
 	var fn *ast.FuncDecl
 	for _, decl := range file.Decls {
 		d, ok := decl.(*ast.FuncDecl)
 		if ok && d.Name.Name == "main" && d.Recv == nil {
 			fn = d
 			break
 		}
 	}
 	if fn == nil {
 		t.Fatal("no func main in main.go — this test read the wrong file")
 	}
 	if len(fn.Body.List) == 0 {
 		t.Fatal("func main is empty")
 	}
 	if !claimsMainOnce(fn.Body.List[0]) {
 		t.Fatalf("the first statement of main() must be the "+
 			"`if !claimMainOnce() { return }` guard, got %T — see #52: "+
 			"Android calls main() once per activity, in a process that "+
 			"outlives the activity, so anything above the guard runs "+
 			"again on every recreation", fn.Body.List[0])
 	}
 }
 // claimsMainOnce reports whether stmt is `if !claimMainOnce() { return }`.
 func claimsMainOnce(stmt ast.Stmt) bool {
 	ifStmt, ok := stmt.(*ast.IfStmt)
 	if !ok {
 		return false
 	}
 	unary, ok := ifStmt.Cond.(*ast.UnaryExpr)
 	if !ok || unary.Op != token.NOT {
 		return false
 	}
 	call, ok := unary.X.(*ast.CallExpr)
 	if !ok {
 		return false
 	}
 	ident, ok := call.Fun.(*ast.Ident)
 	if !ok || ident.Name != "claimMainOnce" {
 		return false
 	}
 	if len(ifStmt.Body.List) != 1 {
 		return false
 	}
 	_, ok = ifStmt.Body.List[0].(*ast.ReturnStmt)
 	return ok
 }
@@ -0,0 +1,196 @@
 #!/usr/bin/env bash
 #
 # Install a built APK onto an Android target and launch it, under the
 # package id the APK itself declares.
 #
 # This is the whole body of build/android/Taskfile.yml's four adb-driven
 # tasks — deploy-emulator, run, run:device, deploy-device — which were
 # three lines each, written out four times, and wrong in two ways in all
 # four (#159):
 #
 #   adb uninstall app.yellowjacket    # the RELEASE id, unconditionally
 #   adb install    bin/yellowjacket.apk
 #   adb shell am start -n app.yellowjacket/com.wails.app.MainActivity
 #
 # **The uninstall is not here and does not come back.**  It was there 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:
 # an error message carrying the command is a decision the person at the
 # keyboard gets to make, which is the same answer scripts/android-
 # emulator.sh already reached for `make android-install`.
 #
 # **The id is read back from the artifact**, never defaulted, so the
 # thing installed and the thing launched cannot disagree — see
 # scripts/android-pkgid.sh for why that is by construction rather than
 # by discipline.
 #
 # **The target is checked against the task's own name.**  The emulator
 # tasks used a bare `adb`, which with one device attached picks that
 # device whatever it is — so `wails3 task android:run`, whose summary
 # says "in the Android Emulator", installed on the phone when a phone
 # was the only thing plugged in.  A task addressing something other than
 # what it says is the same fault as the package id, one level up.
 #
 # Usage:
 #   android-deploy.sh --apk <path> --target emulator|device|any \
 #                     [--expect <id>] [--serial <s>] [--no-launch]
 set -euo pipefail
 cd "$(dirname "$0")/.."
 SDK="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/Android/Sdk}}"
 ADB="$(command -v adb || echo "$SDK/platform-tools/adb")"
 # **Not "$PKG/.MainActivity".**  A leading-dot activity is resolved
 # against the applicationId, and the scaffold's activity lives in the
 # Java package com.wails.app, which is deliberately not it.  The short
 # form fails with a class-not-found that reads like a broken build.
 ACTIVITY="${YJ_ANDROID_ACTIVITY:-com.wails.app.MainActivity}"
 APK=""
 TARGET="any"
 EXPECT=""
 SERIAL="${ANDROID_SERIAL:-${DEVICE_ID:-}}"
 LAUNCH=1
 die() { echo "android-deploy: $*" >&2; exit 1; }
 while [ $# -gt 0 ]; do
 	case "$1" in
 	--apk) APK="${2:-}"; shift 2 ;;
 	--target) TARGET="${2:-}"; shift 2 ;;
 	--expect) EXPECT="${2:-}"; shift 2 ;;
 	--serial) SERIAL="${2:-}"; shift 2 ;;
 	--no-launch) LAUNCH=0; shift ;;
 	*) die "unknown option $1" ;;
 	esac
 done
 [ -n "$APK" ] || die "--apk is required"
 [ -f "$APK" ] || die "no such APK: $APK
    Build one first:  wails3 task android:assemble:apk   (debug)
                      wails3 task android:package        (release)"
 [ -x "$ADB" ] || command -v adb >/dev/null ||
 	die "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
 case "$TARGET" in
 emulator | device | any) ;;
 *) die "--target must be emulator, device or any (got '$TARGET')" ;;
 esac
 # ---------------------------------------------------------------- #
 # Which package
 # ---------------------------------------------------------------- #
 # This runs *before* a target is chosen, deliberately: the guard is a
 # question about the artifact, so it can be answered — and exercised —
 # with nothing plugged in, and a build whose id is wrong should be
 # refused whether or not there is anything to install it onto.
 #
 # An unreadable APK, or an id that is not the one the caller named, is a
 # hard stop before anything is installed or launched.  Spelled as two
 # calls rather than one with a conditional argument: an empty array under
 # `set -u` is an unbound variable in bash 3.2, which is what macOS ships.
 if [ -n "$EXPECT" ]; then
 	PKG="$(./scripts/android-pkgid.sh "$APK" --expect "$EXPECT")"
 else
 	PKG="$(./scripts/android-pkgid.sh "$APK")"
 fi
 # ---------------------------------------------------------------- #
 # Which target
 # ---------------------------------------------------------------- #
 # An emulator serial is "emulator-<port>"; anything else online is a
 # physical device.  That is the same test the device tasks already made,
 # and the emulator tasks did not make at all.
 online_matching() {
 	case "$TARGET" in
 	emulator) "$ADB" devices | awk 'NR > 1 && $2 == "device" && $1 ~ /^emulator-/ { print $1 }' ;;
 	device) "$ADB" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1 }' ;;
 	any) "$ADB" devices | awk 'NR > 1 && $2 == "device" { print $1 }' ;;
 	esac
 }
 if [ -z "$SERIAL" ]; then
 	matches="$(online_matching)"
 	count="$(printf '%s' "$matches" | grep -c . || true)"
 	if [ "$count" -eq 0 ]; then
 		echo "android-deploy: no ${TARGET/any/attached} target is online." >&2
 		"$ADB" devices | sed '1d;/^$/d;s/^/    /' >&2 || true
 		if [ "$TARGET" = "emulator" ]; then
 			echo "    Start one with:  make android-emulator" >&2
 		elif [ "$TARGET" = "device" ]; then
 			echo "    Plug a phone in and authorise the adb key." >&2
 		fi
 		exit 1
 	fi
 	# Several is ambiguous, and picking the first silently is how a
 	# build lands on a target nobody named.  The old run:device did
 	# exactly that.
 	if [ "$count" -gt 1 ]; then
 		echo "android-deploy: several $TARGET targets are online — name one." >&2
 		printf '%s\n' "$matches" | sed 's/^/    /' >&2
 		echo "    Pass DEVICE_ID=<serial>, or set ANDROID_SERIAL." >&2
 		exit 1
 	fi
 	SERIAL="$matches"
 fi
 # ---------------------------------------------------------------- #
 # Install
 # ---------------------------------------------------------------- #
 echo "android-deploy: $APK ($PKG) -> $SERIAL"
 if ! out="$("$ADB" -s "$SERIAL" install -r "$APK" 2>&1)"; then
 	printf '%s\n' "$out"
 	case "$out" in
 	*INSTALL_FAILED_UPDATE_INCOMPATIBLE* | *"signatures do not match"*)
 		cat >&2 <<EOF
 The copy of $PKG already installed was signed with a different key, and
 Android never allows that as an update.
 The only way forward is an uninstall — **which deletes that app's data**,
 and for this app that is the user's library, irreversibly.  So it is not
 done for you.  If the installed copy is disposable:
    $ADB -s $SERIAL uninstall $PKG
 If it is not — if this is a released build with a real library on it —
 install the debug variant instead, which carries applicationIdSuffix
 ".dev" and so sits beside it rather than replacing it:
    wails3 task android:assemble:apk
 EOF
 		;;
 	*INSTALL_FAILED_VERSION_DOWNGRADE*)
 		cat >&2 <<EOF
 The installed copy of $PKG has a higher versionCode than this build.
 A bare 'make android' builds versionCode 1; a versioned one builds e.g.
 10301.  Either build with a version:
    YJ_VERSION=1.3.1 YJ_VERSION_CODE=10301 make android
 or, if the installed copy is disposable, remove it:
    $ADB -s $SERIAL uninstall $PKG
 EOF
 		;;
 	esac
 	exit 1
 fi
 printf '%s\n' "$out"
 [ "$LAUNCH" -eq 1 ] || exit 0
 "$ADB" -s "$SERIAL" shell am start -n "$PKG/$ACTIVITY"
@@ -34,7 +34,21 @@ cd "$(dirname "$0")/.."
 AVD="${YJ_AVD:-yj-test}"
 SDK="${ANDROID_SDK_ROOT:-${ANDROID_HOME:-$HOME/Android/Sdk}}"
-PKG="${YJ_ANDROID_PKG:-app.yellowjacket}"
+# The third declaration of the app's identity, and the one #159 did not
 # cash out in -- but the same hazard, so it is derived rather than
 # written down too. The APK in bin/ is what `make android-install` is
 # about to install and what `android-launch`, `logs` and `smoke` are
 # about to address, so it is the authority; whatever Gradle resolved the
 # applicationId to, suffix included, is in the file.
 #
 # The literal survives only as the answer for a tree with no APK built
 # yet, where these commands are asking about whatever is already on the
 # device and there is nothing to read. YJ_ANDROID_PKG still overrides.
 PKG="${YJ_ANDROID_PKG:-}"
 if [ -z "$PKG" ] && [ -f bin/yellowjacket.apk ]; then
 	PKG="$(./scripts/android-pkgid.sh bin/yellowjacket.apk 2>/dev/null || true)"
 fi
 PKG="${PKG:-app.yellowjacket}"
 # Where `make android-inspect` forwards the WebView's devtools socket.
 CDP_PORT="${YJ_ANDROID_CDP_PORT:-9222}"
 # **Not "$PKG/.MainActivity".** A leading-dot activity is resolved
@@ -281,15 +295,24 @@ cmd_inspect() {
 	need_sdk
 	pick_device || die "no device -- plug a phone in (USB debugging on) or run 'make android-emulator'"
-	local pkg pid
+	local pkg pid candidates
 	pid=""
-	for pkg in "$PKG.dev" "$PKG"; do
+	# Debug sibling first, release second, whichever way round $PKG was
 	# resolved -- it is read from the built APK now, so it is already the
 	# .dev id whenever a debug build is what is in bin/, and appending a
 	# second ".dev" to it would probe a package that cannot exist.
 	case "$PKG" in
 	*.dev) candidates="$PKG ${PKG%.dev}" ;;
 	*) candidates="$PKG.dev $PKG" ;;
 	esac
 	for pkg in $candidates; do
 		pid=$("$ADB" shell pidof "$pkg" 2>/dev/null | tr -d '\r' | awk '{print $1}')
 		[ -n "$pid" ] && break
 	done
-	[ -n "$pid" ] || die "neither $PKG.dev nor $PKG is running; launch it first"
+	[ -n "$pid" ] || die "none of: $candidates is running; launch it first"
 	"$ADB" forward --remove-all >/dev/null 2>&1 || true
 	"$ADB" forward "tcp:$CDP_PORT" "localabstract:webview_devtools_remote_$pid" >/dev/null \
@@ -0,0 +1,97 @@
 #!/usr/bin/env bash
 #
 # Print the package id an APK actually declares — and, given --expect,
 # refuse when that is not the id the caller was about to act on.
 #
 # This exists because the identity is declared twice and nothing made
 # the two agree.  `applicationId` in build/android/app/build.gradle is
 # what Gradle installs; `APP_ID` in build/android/Taskfile.yml was what
 # every adb-driven task uninstalled, launched and filtered.  They differ
 # for a reason nobody has to get wrong: the debug buildType carries
 # `applicationIdSuffix ".dev"`, so a debug build is app.yellowjacket.dev
 # while the default was app.yellowjacket — the *release* id, and on a
 # real phone the released app with the user's library on it (#159).
 #
 # So the id is read back from the artifact rather than written down a
 # third time.  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.
 #
 # Usage:
 #   android-pkgid.sh <apk> [--expect <id>]
 #
 # Exit codes: 0 printed the id; 1 could not read it; 2 --expect failed.
 set -euo pipefail
 die() { echo "android-pkgid: $*" >&2; exit 1; }
 APK=""
 EXPECT=""
 while [ $# -gt 0 ]; do
 	case "$1" in
 	--expect) EXPECT="${2:-}"; shift 2 ;;
 	-*) die "unknown option $1" ;;
 	*) APK="$1"; shift ;;
 	esac
 done
 [ -n "$APK" ] || die "usage: android-pkgid.sh <apk> [--expect <id>]"
 [ -f "$APK" ] || die "no such APK: $APK"
 # aapt2 lives under build-tools/<version>/, which is versioned, so it is
 # resolved rather than pinned.  PATH first, so a system aapt2 (Arch ships
 # one) works without an SDK layout at all.
 find_aapt() {
 	local sdk name
 	for name in "$@"; do
 		command -v "$name" 2>/dev/null && return 0
 	done
 	sdk="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/Android/Sdk}}"
 	for name in "$@"; do
 		ls "$sdk"/build-tools/*/"$name" 2>/dev/null | sort -V | tail -1 | grep . && return 0
 	done
 	return 1
 }
 pkg=""
 # `aapt2 dump packagename` answers in one word and is the cheapest of
 # the three.  aapt1 is the fallback because it is what older build-tools
 # carry and what the issue's own measurement used.
 if AAPT2="$(find_aapt aapt2)"; then
 	pkg="$("$AAPT2" dump packagename "$APK" 2>/dev/null | head -1 | tr -d '\r')" || true
 fi
 if [ -z "$pkg" ] && AAPT="$(find_aapt aapt)"; then
 	pkg="$("$AAPT" dump badging "$APK" 2>/dev/null |
 		sed -n "s/^package: name='\([^']*\)'.*/\1/p" | head -1)" || true
 fi
 # Guessing here is the bug this file exists to prevent, so an unreadable
 # APK is a hard failure and never a fallback to a written-down default.
 if [ -z "$pkg" ]; then
 	die "could not read a package name from $APK.
    Install the SDK build-tools (aapt2), or set ANDROID_HOME to an SDK
    that carries them:  sdkmanager 'build-tools;34.0.0'"
 fi
 if [ -n "$EXPECT" ] && [ "$EXPECT" != "$pkg" ]; then
 	cat >&2 <<EOF
 android-pkgid: refusing to act on a package this APK does not declare.
    the APK declares:  $pkg
    the task expects:  $EXPECT
    APK:               $APK
 These must agree, and when they do not it is the *expectation* that is
 wrong: the APK is what Gradle built.  A debug build carries
 applicationIdSuffix ".dev" (app/build.gradle), so a task that assembles
 a debug APK and then addresses the unsuffixed id is addressing the
 released app — which on a real device is the user's install, with their
 library in it (#159).
 EOF
 	exit 2
 fi
 printf '%s\n' "$pkg"