docs: record the back/forward chrome and the two launch navigations

Both belong beside the rules that already keep the history stack
honest: the depth counting, because forward is the case one counter
cannot express, and the second launch navigation, because it is what
silently defeated the first rule on the list.

.planning/NOTES.md

@@ -3580,3 +3580,119 @@ per-card flag can answer at all.
 The general point: **two columns that agree today are not one column.**
 Which of them a new surface reads should be decided by which one has
 something that can un-set it.
+
+## The queue panel was a column that could not afford to be one (measured 2026-08-19)
+
+Plan 018, issue #24. Measured against the running app (`make
+dev-headless SEED=default`, Chromium) on Playlists, sweeping the
+viewport with the queue open and closed. Main panel width, and how much
+of the page header survived:
+
+| viewport | sidebar | main (queue open) | actions clipped |
+|---|---|---|---|
+| 1280×800 | 200 | 759 | — |
+| 1000×700 | 200 | 479 | 2 of 3 |
+| **900×600** | 200 | **379** | all three |
+| 800×600 | 56 | 423 | all three |
+| 390×780 | — | **69** | all three |
+| 320×600 | — | **0** | all three |
+| 800×600 | 56 | 744 *(closed)* | New Smart Playlist, 158/162px |
+
+Five things came out of it that the issue did not say.
+
+- **The header clips at the enforced minimum with the queue closed.**
+  800×600 is the only size this app promises, and "New Smart Playlist"
+  loses 4px of its 162 there. The queue makes it dramatic; it is not
+  the cause.
+- **900×600 is worse than 800×600.** `AUTO_COLLAPSE_VIEWPORT` collapses
+  the sidebar *below* 900, so the main panel is 843px at 899 and 700px
+  at 900. **The worst desktop case is the top of the Compact band, not
+  the enforced floor** — so every viewport list that stopped at "the
+  minimum" was missing its own worst case. `layout-overflow.spec.ts`
+  carries 900 now.
+- **At 320px the main panel was 0px.** The panel is `flex-shrink: 0` in
+  the flow of `.content-area`, so an open queue is paid for by the
+  content rather than covering it. Not degraded — gone. That is the
+  measurement #55 wanted and did not have.
+- **Only Playlists overflows.** All ten primary views swept at 900×600
+  and 390×780; every other header reports `scrollWidth ==
+  clientWidth`, and Albums at 390 renders title, count and sort legibly
+  (checked on a screenshot, not just the number). So #69 is one view's
+  action set — three text buttons totalling 390px — and not a systemic
+  header failure.
+- **Both reasons in `MinWidth`'s comment had expired.** The subtitle is
+  `display: none` from 899 down, and the sidebar host is
+  `overflow-y: auto` (at 600×460, `scrollHeight` 434 against a 332px
+  client, Settings reachable after scrolling). The floor is right; its
+  stated defence was two mechanisms that can no longer happen, which is
+  worse than either answer because nobody can argue with it.
+
+**A correction worth keeping, because it nearly went in the plan.** My
+first probe for the sidebar's scroller searched
+`shadowRoot.querySelectorAll('*')` and reported "no scroller — items
+are unreachable", which reads exactly like a live Settings-unreachable
+bug. The scroller is the **host**, and a host is not inside its own
+shadow root. CLAUDE.md was right and the probe was wrong.
+
+**And one claim in the plan's first draft was too strong**: that the
+overlay "removes the desktop half of #69". After phase 2, at 900×600,
+open and closed are now *identical* (main 700, one action clipped)
+where open used to be main 379 with all three clipped. The queue's
+contribution is gone; the header's own overflow remains and is still a
+live defect at a supported size.
+
+### The mode cannot be a media query
+
+The panel is drag-resizable 200–500px and persisted, so a viewport
+breakpoint assumes the default 320 and is wrong by up to 180px for a
+user who widened it — in the direction that hurts, since a wider queue
+is exactly when the content can least afford it. It is computed from
+`.content-area`'s width instead (which already accounts for the
+sidebar's collapse), and the component test that matters widens the
+panel at a *fixed* parent width and asserts the flip.
+
+The floor (480) is a judgement, and the measurement is why: there is no
+cliff. The track list rescales its columns continuously — 213px down to
+124px between main widths of 900 and 544, `rowOverflow=0` at every step
+— and the album grid steps 3 columns to 2 somewhere between 564 and 644
+without breaking. So 480 is anchored at both ends instead: it keeps the
+default 1100px window inline, and puts every measured-broken case on
+the overlay side.
+
+The scrim is perceptible but subtle on a dark ramp, which is worth
+knowing before someone "fixes" it as broken: sampled from screenshots at
+900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
+row's text 242 → 133. It covers the content area only — not the sidebar
+or the transport — because the queue is not modal.
+
+## No test tier can see a `hover:` media query (measured 2026-08-19)
+
+Gating an affordance on `(hover: hover) and (pointer: fine)` — #68's fix
+for the play button that flashed on a long-press — is invisible to both
+browser tiers, in *different* ways, and neither of them fails.
+
+- **`make ui-test`**: CDP's `Emulation.setEmulatedMedia` with a `hover`
+  feature does not reach the tier's iframe. The call succeeds and
+  `matchMedia('(hover: hover)')` still answers `true` afterwards. So
+  there is no way to render a component as a phone would and read the
+  computed style.
+- **`make e2e`**: both projects are desktop (`Desktop Chrome`,
+  `Desktop Safari`), and the phone specs reach phone *width* with
+  `setViewportSize`, which changes no media feature but `width`. So the
+  phone specs run with `hover: hover` and the gate is never exercised.
+
+What does work, and what the fix was verified with, is a second browser
+context under a device descriptor: `chromium.newContext(devices['Pixel
+5'])` reports `hover=false pointer:fine=false` and the button computes
+`display: none`, against `flex` at 1440px. That is a one-off script, not
+a spec — `isMobile` is Chromium-only, so it cannot become an e2e project
+without losing the WebKit half.
+
+`hover-affordance.test.ts` therefore asserts the *parsed stylesheet* —
+that the reveal rule sits inside the media query — which catches the
+regression that actually threatens it: someone hoisting the rule back out
+as a tidy-up, a change nothing on a desktop renders differently.
+
+Related: a width-gated decision **is** testable at both tiers, which is
+why #61's phone mini player is a `matchMedia` stub in the component test
+and needs nothing special.

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

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

CLAUDE.md

@@ -945,13 +945,93 @@ change at all.
 
 Two rules hold it up. The **first** navigation *replaces* the launch
 entry rather than pushing one, or every launch costs a back press before
-the app will close. And the in-app back buttons (`navigate-back`, fired
+the app will close. **There are two launch navigations**, which is what
+defeated that rule for five phases: the eager `navigate → home` at the
+foot of `index.ts` and the configured page `GetDefaultPage()` resolves
+to later. Only the first replaced, so a fresh session was already one
+entry deep, the first back press replayed home over home, and on Android
+`canGoBack()` was true so the press that should have exited the app did
+nothing (#142). The landing-page navigation carries `_replace`, honoured
+only while still at index 0 — past that the user has navigated during
+the backend call, and a slow answer must not overwrite an entry they
+made. And the in-app back buttons (`navigate-back`, fired
 by the detail views and `now-playing-view`) go through `history.back()`
 rather than a stack of their own: the old `navStack` is **deleted**, not
 kept beside it, because two stacks is precisely how a view's own back
 button and the phone's gesture come to disagree about what one press
 means.
 
+**And there is one statement of which view is active**, for the same
+reason: `popstate` calls `handleNavigate()` directly and dispatches no
+`navigate`, so the two nav components — which learned the active view
+from that event — kept highlighting the view the user had just *left*.
+`store/active-view-store.ts` is the shell saying where the user is, and
+both navs read it through `ActiveViewController` rather than holding an
+`activeView` of their own.
+
+Four things about it are load-bearing.
+
+**"Please go to X" and "the active view is now X" are different
+statements**, and only the first existed — dispatched from 28 call
+sites across 18 files. A re-dispatch from inside `handleNavigate` is
+not the fix and cannot be: that function is the `document` listener for
+`navigate`, so it is an infinite loop.
+
+**It is a store rather than an event, because a component that mounts
+after a navigation still has to know.** `bottom-nav`'s "More" drawer
+creates its `<app-sidebar>` on open, and that copy had heard no
+`navigate` at all — standing on Albums, the drawer opened highlighting
+Home. An event has no answer for a listener that was not there.
+
+**A detail view is not a view here**, so the destination it was opened
+from stays lit. `app-sidebar` did that by accident (it guarded on
+`navItems.some(...)`, so an unmatched name left its highlight alone)
+and `bottom-nav` had no such guard and so lit *nothing* — which is why
+one looked right and the other looked broken on the same screen.
+Whether a view is primary is the shell's fact: `view in VIEW_TAGS` is
+passed to `setView`, never re-derived, because a second copy of that
+list is a second thing to forget.
+
+**Nothing is lit until the shell has navigated.** The store starts
+empty rather than defaulting to `home`, which is what `app-sidebar`'s
+field used to do to match the landing view — a default that is correct
+only while `GetDefaultPage()` agrees with it.
+
+**Back and forward are chrome, and the depth is the shell's own
+count.** `<nav-history>` in the top bar is #6: the stack was always
+global — every navigation is an entry and `popstate` restores any of
+them in either direction — so what was missing was an affordance, since
+the only way back was a detail view's own button, which leaves the
+screen with the view it belongs to. The buttons dispatch
+`navigate-back` / `navigate-forward` and the shell owns both guards,
+for the reason the old `navStack` was deleted: a second caller reaching
+for `history` is how two stacks come to disagree.
+
+Three things about it are load-bearing. **Forward is not back
+negated**, so the single `pushedEntries` counter could not express it —
+`popstate` carries no direction and fires identically both ways, so a
+counter decremented on every pop reads a forward as a second back. Each
+entry carries its index (`yjIdx`) and the shell keeps the current one
+and a high-water mark; that also survives a jump of more than one,
+which `history.go(-n)` and a long-press on a browser's back button both
+produce. **A control that cannot act is `disabled` here**, which is the
+documented exception to `library-status-indicator`'s rule: the two are
+a pair whose positions the user learns, and hiding one moves the other
+under the cursor. And **it stands down below 900px** — the top bar is
+what runs out of room first below that (it already overflows 600px by
+11px, #143), and nothing becomes unreachable: `nav.back` / `nav.forward`
+(`Alt+Left` / `Alt+Right`, the browser's own combination, and clear of
+the bare arrows that seek) are global at every width, and the phone has
+the platform's gesture.
+
+The assertion is `aria-current="page"`, in
+`e2e/specs/back-navigation.spec.ts`. That file existed throughout the
+bug, covered exactly these journeys, and asserted only
+`data-active-view` — the shell's own bookkeeping, which was right the
+whole way through — so it was green on the broken build. Same trap as
+`layout-overflow.spec.ts` and `page-header`: a spec named for the
+behaviour, measuring the plumbing.
+
 **A primary view is cached, not unmounted.** `index.ts` keeps every
 primary view in the DOM and toggles a `.view-hidden` class, because that
 is what preserves `scrollTop` across navigation — so
@@ -1328,6 +1408,68 @@ is 32px each. Which four is plan 016's committed subset, and everything
 else — Settings included, because a phone still needs it — is behind
 "More".
 
+**There are three supported size bands, and the queue is part of the
+promise.** Plan 018 (#24) wrote them down: **Phone** below 600 (bottom
+nav, reflows, fits 320px exactly), **Compact** 600–899 (icon sidebar),
+**Desktop** from 900 (labelled sidebar) — plus one sentence across all
+three, *no action is ever unreachable at any supported size*. The bands
+themselves already existed; what was new is that they are a promise and
+that the queue panel is inside it.
+
+**900 is the worst desktop width, not the 800×600 minimum.** The
+sidebar collapses to icons *below* 900, so the main panel is 843px at
+899 and 700px at 900 — the narrowest content area any desktop width
+produces is at the top of the Compact band, not at the enforced floor.
+Every viewport list that stopped at "the minimum" was therefore missing
+its own worst case, which is why `layout-overflow.spec.ts` carries 900
+now. And **both reasons in `MinWidth`'s comment had expired** — the
+subtitle is `display: none` from 899 down and the sidebar host scrolls
+(`overflow-y: auto`; at 600×460 its `scrollHeight` is 434 against a
+332px client) — so 800×600 is a *comfort* floor for desktop chrome and
+not a correctness one. Below it the phone layout takes over, which is
+also why a very small window reflows rather than becoming a
+mini-player: **#12 is a second always-on-top window, not a mode of this
+one**, and making it a mode would discard navigation state on a resize
+and put the process-level MPRIS question on a path a drag can trigger.
+
+**The queue panel is a column only while the content can spare the
+width, and that cannot be a media query.** In flow the host is
+`flex-shrink: 0`, so an open queue is paid for by the main panel: it
+left 379px at 900×600 (with all three of the Playlists header's actions
+clipped), 69px at 390, and **0px** at 320 — the content was not
+degraded but gone. It goes to an overlay with a scrim when
+`available - panelWidth < 480`, where `available` is
+`.content-area`'s width and therefore already accounts for the
+sidebar's collapse.
+
+Four things about it are load-bearing. **The mode is computed, not
+breakpointed**, because the panel's width is user state — drag-resizable
+200–500px and persisted — so a viewport breakpoint silently assumes the
+default 320 and is wrong by up to 180px in the direction that hurts;
+widening the panel at a fixed window size must flip it, and
+`queue-overlay-mode.test.ts` is written around exactly that. **480 is a
+judgement and says so**: there is no cliff to derive it from (the track
+list rescales continuously, 213px to 124px columns with no row
+overflow), so it is anchored to keep the default 1100px window inline
+and put every measured-broken case on the overlay side. **The scrim
+covers the content area only** — not the sidebar or the transport —
+because the queue is not modal, and it is subtle on a dark ramp by
+arithmetic rather than by accident (33,37,41 → 18,20,23). And **the
+overlay is a presentation, not a fork**: #55 asks for one component
+with two mount points, so the roving tab stop, Alt+Arrow reorder, drag
+reorder, selection semantics and `virtualizer.requestUpdate()` all come
+along untouched. Escape closes it and returns focus, and is attached
+only while the overlay is up — it is a dismissal, not a shortcut, which
+is why it is not a panel-scoped binding.
+
+What this does **not** fix is `page-header` overflowing on its own:
+at 900×600 "New Smart Playlist" is still clipped to 114 of 162px with
+the queue *closed*. That is #69, and it cannot be fixed in
+`page-header` alone — actions arrive through `<slot name="actions">` as
+arbitrary light-DOM markup with their own handlers, so collapsing them
+into a "More actions" menu needs an actions *API* (data, not markup)
+across all three hosts that slot them.
+
 **The phone section of `index.css` is last on purpose.** A media query
 adds no specificity, so a `@media (max-width: 599px)` block placed
 above the plain rules it overrides loses to them — which is how phase 1
@@ -1918,6 +2060,79 @@ that corrects itself a moment later is worse than saying nothing. And
 the field, the direction and their persistence, so the control cannot
 disagree with the list.
 
+**And an action is data, on that same rule: the header decides what
+fits, the host decides what happens.** Playlists slotted three buttons
+totalling 390px into a header that gets 700px at 900×600, so "New Smart
+Playlist" rendered **114 of its 162px** with the queue closed — and on a
+phone none of them could be reached at all, which is what #69 reported.
+A host passes `PageAction[]` (`{id, label, icon, onSelect, priority,
+drop?}`) and `page-header` renders each one as a button or as an item in
+one "More actions" menu.
+
+**It could not have been a rule added in one place**, and that is a fact
+about the API rather than an effort estimate: actions used to arrive
+through `<slot name="actions">` as arbitrary light-DOM markup, and a
+component cannot move another component's light-DOM children into a
+dropdown and keep their behaviour — there is nothing generic in markup
+to render as a menu item. The slot survives for markup a data list
+cannot express, at the stated cost that **a slotted action does not
+collapse** and must therefore fit at 800×600.
+
+Six things about it are load-bearing:
+
+- **The fit is measured, never breakpointed.** A ResizeObserver drives
+  it, and each pass starts from *all visible* and hides the
+  lowest-priority action until it fits — so the collapsed set is a pure
+  function of the current width rather than of how the window got
+  there. A rule that only ever added to the set would never give a
+  button back, and one that adjusted by a step would need a hysteresis
+  band to stop it oscillating on the pixel where a button exactly fits.
+- **"Fits" means nothing is clipped, which is not the same as the
+  header not overflowing.** The title can ellipsis, and the moment it
+  can it absorbs the pressure: `scrollWidth` reports a header that fits
+  perfectly while the heading reads "Playlis…". That is this bug moved
+  from the button to the title, invisible to the same measurement that
+  missed it the first time — so the heading's own truncation counts as
+  not fitting, and an action is collapsed before the title gives way.
+  Below that, at 320px, the title *is* what yields: the navigation also
+  says which page you are on, and an action has nowhere else to be said.
+- **The measurement flips `hidden` on the rendered nodes rather than
+  re-rendering between steps.** Reading `scrollWidth` forces layout,
+  which is the point; awaiting a Lit update between steps instead lets
+  the intermediate all-visible state paint, so the fix would flash the
+  overflow it exists to prevent.
+- **Priority is what a *capability* costs, not what a button is worth.**
+  New Playlist is highest because it is the **drop target** and a closed
+  menu cannot be one; that is also why `PageAction.drop` carries the
+  host's own `dragover`/`dragleave`/`drop` handlers rather than the
+  header owning a notion of dropping, and why the affordance is simply
+  absent from the overflow rather than approximated there.
+- **`aria-controls` names a panel that is always in the DOM** —
+  `config-section`'s rule, and `wa-popup` hides it when inactive — and
+  the keyboard model is `MenuKeyboard`, shared with every other menu in
+  the app so this is not a second one.
+- **It is checked per button, because `layout-overflow.spec.ts` cannot
+  see this.** That spec asserts the *shell* needs no sideways
+  scrolling and passed on the broken build; clipping *inside* a
+  component is invisible to it, which is exactly why the defect
+  survived a spec named for it.
+  `e2e/specs/header-action-overflow.spec.ts` measures each button
+  against its header at 900×600, 800×600, 390×780 and 320×600, and
+  asserts buttons **plus** menu account for every declared action —
+  without that half it would pass vacuously on a build that renders no
+  actions at all.
+
+One thing it deliberately does **not** grow is a phone mode for the
+actions. `PHONE_COLUMN_IDS` is the precedent for "what is drawn and
+what can be sorted are different questions", but it exists because the
+track list's columns cannot be derived from a width; these can, and a
+second declaration of what a phone shows is a second thing to keep in
+step. What the header *does* state at phone width is one word: below
+600px the sort control's "Sort:" label is visually hidden — 172px of a
+320px header for a label the adjacent direction arrow implies — and it
+stays in the accessibility tree, because it is the select's accessible
+name and hiding it outright is `config-field`'s bug one component over.
+
 **The header search box is view-scoped, and now says so.** It sits in
 the app header and reads as global; typing `tide` on Playlists answered
 "No playlists match your search" with three *Tideline* tracks in the
@@ -2307,6 +2522,23 @@ Pre-commit hooks verify generated code is fresh — always run `make generate` a
   mistyped `feat` ships a minor version. `make release-dry` answers "what
   would this merge release" without pushing.
 
+  **The analyzer reads the type and ignores the scope, so a CI-only change
+  is `ci:` and never `fix(ci):`.** The scope is decoration; `fix` is a
+  patch whatever is in the brackets. Two commits touching nothing but
+  `.gitea/workflows/unclaim.yml` were written `fix(ci):` and cut `v0.2.1`
+  and `v0.2.2` — real releases, published to Arch, Homebrew and the APK
+  registry, containing no user-facing change. They were left in place
+  rather than deleted, because a version that vanishes is worse for
+  whoever pulled it than one that turns out to be empty.
+
+  **The blast radius is bigger than the version number**, which is what
+  makes this worth a paragraph. A merge to `main` starts two workflows;
+  if `release.yml` then pushes a tag, that tag push starts **four more**
+  (`arch-package`, `homebrew-formula`, `android-apk`, `desktop-assets`) —
+  on a runner with capacity 1, where the APK build alone is tens of
+  minutes. `make release-dry` before merging is how you find out, and it
+  is cheaper than every one of those.
+
   **`@semantic-release/github` is not in that config and must not be.**
   Gitea's API is `/api/v1` and is not GitHub's surface, so
   `@semantic-release/exec` calls `scripts/gitea-release.sh` instead — one

backend/autotag/recommend.go

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

backend/autotag/recommend_test.go

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

backend/autotagservice/albummatch.go

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

backend/autotagservice/albummatch_test.go

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

backend/config/window.go

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

backend/database/sql/queries/tagging_items.sql

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

backend/database/sql/sqlcgen/tagging_items.sql.go

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

backend/explore/prune_test.go

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

backend/explore/searchindex.go

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

backend/player/buffered_stall_test.go

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

backend/player/buffered_streamer.go

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

backend/player/loadstate_test.go

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

backend/player/player.go

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

backend/queue/fallback_test.go

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

backend/queue/finished_test.go

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

backend/queue/handlers.go

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

backend/queue/playbackfailed_test.go

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

backend/shortcuts/config.go

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

e2e/specs/album-dropdown.spec.ts

@@ -1,6 +1,12 @@
 import { test, expect } from '../support/fixtures.js';
 import type { Page } from '@playwright/test';
 
+/**
+ * How far the scroll test scrolls. One constant, because the guard and
+ * the assertion have to agree about it — they did not, which is #133.
+ */
+const SCROLL_TARGET = 80;
+
 /**
  * Plan 007 phase 5: expanding an album shows its tracks.
  *
@@ -104,20 +110,27 @@ test.describe('the album dropdown', () => {
     await app.setViewportSize({ width: 900, height: 600 });
 
     try {
-      await expect.poll(() => scrollRange(app)).toMatchObject({
-        scrollable: true,
-        overflowY: 'auto',
-      });
+      // Wait for the range the assertion below actually needs, not for
+      // "scrollable at all" (#133). The guard used to be
+      // `scrollHeight > clientHeight + 40` while the next line asks to
+      // 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' });
 
-      await app.evaluate(() => {
+      await app.evaluate((target) => {
         const sc = document
           .querySelector('cover-grid')
           ?.shadowRoot?.querySelector('.grid-scroll-container');
 
-        if (sc) sc.scrollTop = 80;
-      });
+        if (sc) sc.scrollTop = target;
+      }, SCROLL_TARGET);
 
-      expect(await scrollTop(app)).toBe(80);
+      expect(await scrollTop(app)).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
@@ -250,16 +263,19 @@ async function closeDropdown(app: Page): Promise<void> {
 
 /** Whether the grid can scroll at all, which decides if a probe can move. */
 async function scrollRange(app: Page) {
-  return app.evaluate(() => {
+  return app.evaluate((target) => {
     const sc = document
       .querySelector('cover-grid')
       ?.shadowRoot?.querySelector('.grid-scroll-container');
 
     return {
-      scrollable: !!sc && sc.scrollHeight > sc.clientHeight + 40,
+      // `room` is the precondition of the assertion that follows it:
+      // enough range to actually reach the target. A threshold below
+      // what the caller depends on is not a guard.
+      room: !!sc && sc.scrollHeight - sc.clientHeight >= target,
       overflowY: sc ? getComputedStyle(sc).overflowY : '',
     };
-  });
+  }, SCROLL_TARGET);
 }
 
 async function scrollTop(app: Page): Promise<number> {

e2e/specs/back-navigation.spec.ts

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

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

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

e2e/specs/layout-overflow.spec.ts

@@ -26,6 +26,12 @@ const MIN_VIEWPORT = { width: 800, height: 600 };
 const VIEWPORTS = [
   { name: '1440×900', width: 1440, height: 900 },
   { name: '1024×768', width: 1024, height: 768 },
+  // Not the minimum, and that is the point (#24). The sidebar collapses
+  // to icons *below* 900, so the main panel is 843px at 899 and 700px
+  // at 900 — the narrowest content area any desktop width produces is
+  // here, not at the enforced floor. A list that stopped at the minimum
+  // was missing its own worst case.
+  { name: '900×600 (the widest sidebar, so the narrowest content)', width: 900, height: 600 },
   { name: `the minimum (${MIN_VIEWPORT.width}×${MIN_VIEWPORT.height})`, ...MIN_VIEWPORT },
 ];
 

e2e/specs/queue-overlay.spec.ts

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

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

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

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

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

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

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

frontend/bindings/yellowjacket/backend/queue/queue.ts

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

frontend/index.css

@@ -104,6 +104,15 @@ p {
     flex: 0 1 320px;
 }
 
+/* The bar is `justify-content: space-between`, which with four children
+   spreads them evenly and left back/forward floating in the middle of
+   nothing. Collecting the free space *after* this one puts the pair
+   beside the brand, where a browser keeps them, and leaves the
+   right-hand group exactly as it was. */
+.top-bar nav-history {
+    margin-right: auto;
+}
+
 ul {
     list-style-type: none;
 }
@@ -133,6 +142,23 @@ ul {
     .subtitle {
         display: none;
     }
+
+    /* Back/forward is Desktop-band chrome (#6), and 900 is the same
+       line the sidebar's labels and the subtitle are already given up
+       at -- below it the shell is narrow enough that the header is
+       what runs out of room first. Measured at 600, the bottom of the
+       Compact band: the bar is 611px inside a 600px viewport *before*
+       this component exists (filed separately), and 695px with it, so
+       keeping it here would be widening a violation of the promise
+       that nothing scrolls sideways at a supported size.
+
+       Nothing is unreachable as a result, which is the rule that
+       decides it: Alt+Left / Alt+Right are global and every width has
+       them, the detail views keep their own back buttons, and the
+       phone additionally has the platform's gesture. */
+    .top-bar nav-history {
+        display: none;
+    }
 }
 
 body div.sidebar {
@@ -231,6 +257,14 @@ body div.sidebar {
     display: flex;
     overflow: hidden;
     contain: layout style;
+
+    /* The containing block for the queue panel's overlay mode (plan
+       018, #24), which spans this box rather than taking width from
+       the main panel beside it. `contain: layout` already establishes
+       one; this says so on purpose, so that removing the containment
+       for a paint reason does not silently reparent the overlay to the
+       viewport. */
+    position: relative;
 }
 
 .main-panel {
@@ -338,7 +372,13 @@ body div.sidebar {
 
     /* The search box is the one header control worth its width; the
        library filter is a rarely-changed setting and reachable from
-       the drawer's Settings. */
+       the drawer's Settings.
+
+       `nav-history` is already gone from 899 down. It would belong
+       here anyway and for a stronger reason than width: the phone has
+       Back as a gesture or a button the OS owns, and this app hooks it
+       (`popstate`), so a second Back in the chrome duplicates a
+       control the platform provides. */
     .top-bar library-filter {
         display: none;
     }

frontend/index.html

@@ -20,6 +20,12 @@
             <!-- a11y.29: a heading level was being used for type size. -->
             <p class="subtitle">Music how it was meant to bee.</p>
         </hgroup>
+        <!-- Global back/forward (#6). Before the library filter so the
+             two navigation controls in this bar are adjacent, and after
+             the brand because that is where a window's chrome ends and
+             the app's begins. Hidden below 600px by index.css: the
+             phone has a system back, and this bar has no room. -->
+        <nav-history></nav-history>
         <library-filter></library-filter>
         <search-bar></search-bar>
         <job-indicator></job-indicator>

frontend/index.ts

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

frontend/src/assets/icons/fa/solid/arrow-right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.3.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2026 Fonticons, Inc. --><path fill="currentColor" d="M502.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-160-160c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L402.7 224 32 224c-17.7 0-32 14.3-32 32s14.3 32 32 32l370.7 0-105.4 105.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0l160-160z"/></svg>

frontend/src/assets/icons/fa/solid/ellipsis.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.3.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2026 Fonticons, Inc. --><path fill="currentColor" d="M0 256a56 56 0 1 1 112 0 56 56 0 1 1 -112 0zm168 0a56 56 0 1 1 112 0 56 56 0 1 1 -112 0zm224-56a56 56 0 1 1 0 112 56 56 0 1 1 0-112z"/></svg>

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

@@ -1315,13 +1315,40 @@ export class AutotagView extends ViewLifecycleMixin(LitElement) {
         // the page only needs the folder list, which is local and may
         // have moved while the page was away.
         if (this.queueStarted) {
-            void this.loadFolders();
+            void this.loadFolders().then(() => this.openRequestedFolder());
         } else {
             this.queueStarted = true;
-            void this.startQueue();
+            void this.startQueue().then(() => this.openRequestedFolder());
         }
     }
 
+    /**
+     * Open the folder somebody navigated here to look at.
+     *
+     * The album page's "Review in Autotag" has to land on *that*
+     * album. The queue is sorted by score so the intended folder is
+     * often near the top, but "often" is a link that sometimes opens
+     * the wrong album, which is worse than no link.
+     *
+     * It is an attribute rather than a property because this is a
+     * **cached primary view**: `index.ts` creates it once and reuses
+     * it, so there is no construction to pass a value to. Which is
+     * also why the request is *consumed* — the attribute is removed
+     * once acted on, or every later visit to Autotag would reopen an
+     * album the user finished with three navigations ago.
+     */
+    private openRequestedFolder(): void {
+        const requested = this.getAttribute('group-key');
+
+        if (!requested) return;
+
+        this.removeAttribute('group-key');
+
+        if (this.current?.groupKey === requested) return;
+
+        void this.selectFolder(requested);
+    }
+
     protected override onViewDeactivate(): void {
         this.unsubscribeLibraryStore?.();
         this.unsubscribeLibraryStore = undefined;

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

@@ -7,6 +7,7 @@ import { designTokens } from '../../styles/tokens.css';
 import '../sidebar/app-sidebar.js';
 import { nameDialog } from '@utils/name-dialog';
 import { ICON_PLAYLIST } from '@utils/icon-language';
+import { ActiveViewController } from '@store/controllers/active-view-controller';
 
 type View = 'home' | 'albums' | 'tracks' | 'playlists';
 
@@ -114,8 +115,19 @@ export class BottomNav extends LitElement {
         }
     `];
 
-    @state()
-    private activeView = 'home';
+    /**
+     * Which tab is lit, read from the shell rather than tracked here.
+     *
+     * This was a `@state()` field set from the `navigate` event, which
+     * only the outbound path dispatches -- so backing out of a detail
+     * view left the highlight wherever it had been (#72). It had no
+     * equivalent of `app-sidebar`'s `navItems.some(...)` guard either,
+     * so a detail view set it to a name matching no tab and *nothing*
+     * was lit; that asymmetry is why one nav looked broken and the
+     * other looked fine. The store answers both: a detail view leaves
+     * the tab it was opened from lit, in both components.
+     */
+    private activeCtrl = new ActiveViewController(this);
 
     /**
      * Whether the drawer has been asked for.
@@ -167,12 +179,9 @@ export class BottomNav extends LitElement {
         nameDialog(this.drawer);
     }
 
-    private onGlobalNavigate = (e: Event) => {
-        const detail = (e as CustomEvent<{ view?: string }>).detail;
-
-        if (detail?.view) this.activeView = detail.view;
-
+    private onGlobalNavigate = () => {
         // A navigation from inside the drawer is the drawer's job done.
+        // The highlight is not this listener's business any more.
         this.drawerOpen = false;
     };
 
@@ -206,9 +215,11 @@ export class BottomNav extends LitElement {
                         <li>
                             <button
                                 type="button"
-                                class=${this.activeView === tab.id ? 'active' : ''}
+                                class=${this.activeCtrl.isActive(tab.id)
+                                    ? 'active'
+                                    : ''}
                                 data-testid="tab-${tab.id}"
-                                aria-current=${this.activeView === tab.id
+                                aria-current=${this.activeCtrl.isActive(tab.id)
                                     ? 'page'
                                     : 'false'}
                                 @click=${() => this.navigate(tab.id)}

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

@@ -81,23 +81,55 @@ export class ConfirmDialog extends LitElement {
         `,
     ];
 
+    /**
+     * Which question is on screen.
+     *
+     * This is a singleton reused for every confirmation in the app,
+     * and `wa-dialog` reports its close *asynchronously* — `open =
+     * false` starts an animation and `wa-hide` arrives after it. So a
+     * hide belonging to a question that has already been answered can
+     * land after the *next* question has opened, and cancel it: the
+     * user is asked something, the dialog vanishes on its own, and the
+     * call site is told they said no.
+     *
+     * The counter is what tells one question from the next. Every
+     * close bumps it, and the `wa-hide` handler carries the id its
+     * template was rendered with.
+     */
+    private askSeq = 0;
+
     /** Ask. Resolves true if the user went ahead. */
     ask(request: ConfirmRequest): Promise<boolean> {
         this.close(false);
+
+        const id = ++this.askSeq;
+
         this.request = request;
 
         return new Promise<boolean>((resolve) => {
             this.settle = resolve;
             void this.updateComplete.then(() => {
-                if (this.dialog) this.dialog.open = true;
+                // A third question could have arrived while this one
+                // was waiting for its own render.
+                if (this.askSeq === id && this.dialog) this.dialog.open = true;
             });
         });
     }
 
-    private close(ok: boolean): void {
+    /**
+     * Settle the current question, if `id` still names it.
+     *
+     * The button handlers pass nothing and always mean the question on
+     * screen; only `wa-hide` carries an id, because only `wa-hide` can
+     * arrive late.
+     */
+    private close(ok: boolean, id = this.askSeq): void {
+        if (id !== this.askSeq) return;
+
         const settle = this.settle;
 
         this.settle = null;
+        this.askSeq++;
 
         if (this.dialog) this.dialog.open = false;
         this.request = null;
@@ -118,11 +150,15 @@ export class ConfirmDialog extends LitElement {
 
         if (!request) return nothing;
 
+        // Captured at render time, so the handler answers the question
+        // it was drawn for and not whichever one is up when it fires.
+        const id = this.askSeq;
+
         return html`
             <wa-dialog
                 label=${request.title}
                 data-testid="confirm-dialog"
-                @wa-hide=${() => this.close(false)}
+                @wa-hide=${() => this.close(false, id)}
             >
                 <p>${request.message}</p>
                 ${request.impact

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

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

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

@@ -30,12 +30,16 @@ import { Events } from '../../events';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '../library-status-indicator/library-status-indicator.js';
 import { libraryStatusFor } from '@utils/library-status';
+import { ICON_AUTOTAG } from '@utils/icon-language';
 import type { LibraryStatus } from '../library-status-indicator/library-status-indicator.js';
 import '../catalog-scope-notice/catalog-scope-notice.js';
 import type { CatalogScope } from '../catalog-scope-notice/catalog-scope-notice.js';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '../download-picker/download-picker';
 import { downloadStore } from '../../store/download-store';
+import { MatchForAlbum, ApplyAsync } from '@go/autotagservice/service.js';
+import type * as autotagservice from '@go/autotagservice/models.js';
+import { confirmAction } from '../confirm-dialog/confirm-dialog';
 import { queueStore } from '../../store/queue-store';
 import type { QueueSource } from '../../store/queue-store';
 import { notificationStore } from '../../store/notification-store';
@@ -175,6 +179,19 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
     @property({ type: Number, attribute: 'local-album-id' })
     localAlbumId = 0;
 
+    /**
+     * A confident autotag match for this album, or null when there is
+     * none worth mentioning.
+     *
+     * The tier behind "confident" is `autotag.ConfidentTier`, decided
+     * in the backend so this page and strict auto-accept cannot
+     * disagree about what it means (#28, #90).
+     */
+    @state() private autotagMatch: autotagservice.AlbumMatchView | null = null;
+
+    /** True while an apply started from this page is in flight. */
+    @state() private applyingTags = false;
+
     /* ── Internal state ── */
 
     @state() private releaseGroup: MBReleaseGroup | null = null;
@@ -198,6 +215,28 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
     @state() private versionEntries: VersionEntry[] = [];
     /** Currently-selected dropdown entry (by VersionEntry.key). */
     @state() private selectedVersionKey: string = '';
+
+    /**
+     * The key `buildClusters` defaulted to, kept so the page can tell
+     * "this is what we picked for you" from "you went and chose this".
+     *
+     * Only the second needs saying out loud. With the selector demoted
+     * to a disclosure below the tracklist, a chosen version is the one
+     * case where the list on screen is not the one the header
+     * describes, and nothing else on the page would say so.
+     */
+    @state() private defaultVersionKey: string = '';
+
+    /**
+     * Whether the "Other versions" disclosure is open.
+     *
+     * Collapsed by default — choosing which pressing you are looking at
+     * is a metadata-repair task and does not belong above the
+     * tracklist. It is deliberately *not* closed when the selection
+     * changes: the user opened it to change something, and a panel that
+     * shuts on use cannot be used twice.
+     */
+    @state() private versionsOpen = false;
     @state() private coverArtURL = '';
 
     /**
@@ -523,7 +562,144 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                 flex-shrink: 0;
             }
 
-            /* ── Version selector ── */
+            /* ── The autotag suggestion ── */
+            .autotag-match {
+                display: flex;
+                align-items: center;
+                flex-wrap: wrap;
+                gap: 8px 12px;
+                margin-bottom: 12px;
+                padding: 10px 14px;
+                border: 1px solid
+                    var(--yj-border-subtle, rgba(255, 255, 255, 0.08));
+                border-radius: 8px;
+                background: var(--yj-surface-1, rgba(255, 255, 255, 0.04));
+            }
+
+            .autotag-match > wa-icon {
+                flex-shrink: 0;
+                font-size: var(--yj-icon-sm);
+                color: var(--yj-text-secondary, #b3b3b3);
+            }
+
+            .autotag-match-text {
+                margin: 0;
+                flex: 1;
+                /* The suggestion sits in a flex row beside its buttons,
+                 * and a grid/flex item's implicit minimum is its
+                 * content — without this a long release title pushes
+                 * the actions off the end at phone width. */
+                min-width: 0;
+                font-size: var(--yj-text-sm);
+                color: var(--yj-text-secondary, #b3b3b3);
+            }
+
+            .autotag-match-text strong {
+                color: var(--yj-text-primary, #fff);
+                font-weight: 600;
+            }
+
+            .autotag-match-note {
+                display: block;
+                margin-top: 2px;
+                font-size: var(--yj-text-xs);
+                color: var(--yj-text-tertiary, #888);
+            }
+
+            .autotag-match-actions {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+                flex-shrink: 0;
+            }
+
+            /* ── Other versions (a disclosure, below the tracklist) ── */
+            .versions {
+                margin-top: 24px;
+                border-top: 1px solid
+                    var(--yj-border-subtle, rgba(255, 255, 255, 0.08));
+                padding-top: 8px;
+            }
+
+            /* The heading exists so the section is reachable by heading
+             * navigation; the button inside it is the control. Its own
+             * type scale is the section header's, reduced — this is a
+             * footnote to the page, not a peer of the tracklist. */
+            .versions-heading {
+                margin: 0;
+                font-size: var(--yj-text-sm);
+                font-weight: 500;
+            }
+
+            .versions-toggle {
+                display: flex;
+                align-items: center;
+                gap: 8px;
+                width: 100%;
+                padding: 8px 2px;
+                background: none;
+                border: none;
+                color: var(--yj-text-secondary, #b3b3b3);
+                font: inherit;
+                text-align: left;
+                cursor: pointer;
+            }
+
+            .versions-toggle:hover {
+                color: var(--yj-text-primary, #fff);
+            }
+
+            .versions-toggle:focus-visible {
+                outline: 2px solid var(--yj-accent-text, #ffd43b);
+                outline-offset: 2px;
+                border-radius: 4px;
+            }
+
+            .versions-toggle wa-icon {
+                font-size: var(--yj-icon-xs, 11px);
+                transition: transform 0.2s ease;
+            }
+
+            .versions-toggle[aria-expanded='false'] wa-icon {
+                transform: rotate(-90deg);
+            }
+
+            .versions-intro {
+                margin: 0 0 10px;
+                font-size: var(--yj-text-xs);
+                color: var(--yj-text-tertiary, #888);
+                line-height: 1.4;
+            }
+
+            /* A line above the tracklist, and only after a deliberate
+             * choice — see renderChosenVersion. */
+            .chosen-version {
+                margin: 0 0 10px;
+                font-size: var(--yj-text-sm);
+                color: var(--yj-text-secondary, #b3b3b3);
+            }
+
+            .chosen-version strong {
+                color: var(--yj-text-primary, #fff);
+                font-weight: 600;
+            }
+
+            .chosen-version-reset {
+                background: none;
+                border: none;
+                padding: 0;
+                font: inherit;
+                color: var(--yj-accent-text, #ffd43b);
+                text-decoration: underline;
+                cursor: pointer;
+            }
+
+            .chosen-version-reset:focus-visible {
+                outline: 2px solid var(--yj-accent-text, #ffd43b);
+                outline-offset: 2px;
+                border-radius: 2px;
+            }
+
             .version-selector {
                 display: flex;
                 flex-direction: column;
@@ -948,10 +1124,20 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         this.releases = [];
         this.versionEntries = [];
         this.selectedVersionKey = '';
+        this.defaultVersionKey = '';
+        this.versionsOpen = false;
         this.showFullTracklist = null;
         this.localTracks = [];
         this.filePaths = new Map();
         this.askedFor = new Set();
+        this.autotagMatch = null;
+
+        // Not awaited: the banner is a bonus and the page must not
+        // wait on it. It is also the *most* useful on an untagged
+        // album, which is exactly the page that has least else to
+        // show, so it is asked for on both branches below rather than
+        // only the catalog one.
+        void this.loadAutotagMatch();
 
         // Local-only album (no MBID) — populate entirely from library.
         if (!mbid && this.localAlbumId) {
@@ -1144,6 +1330,31 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         return this.completeness;
     }
 
+    /**
+     * Ask whether the autotagger already has a confident match here.
+     *
+     * It answers from what the background prefetch has already scored
+     * and makes no MusicBrainz request, so this is safe on page load —
+     * see `MatchForAlbum`. A folder nobody has reached yet answers
+     * `null`, which is the same as "nothing to say": the banner is a
+     * bonus, so a failure is a missing suggestion rather than an error
+     * the user can act on, and it stays in the console.
+     */
+    private async loadAutotagMatch(): Promise<void> {
+        if (this.localAlbumId <= 0) {
+            this.autotagMatch = null;
+
+            return;
+        }
+
+        try {
+            this.autotagMatch = await MatchForAlbum(this.localAlbumId);
+        } catch (err) {
+            console.error('[explore-album] autotag match lookup failed', err);
+            this.autotagMatch = null;
+        }
+    }
+
     /**
      * Fetch and set `localTracks` directly by local album id — the
      * definite source of truth, used when nothing else has already
@@ -1639,6 +1850,14 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
             || standardEntry?.key
             || this.versionEntries[0]?.key
             || '';
+
+        // Recorded here rather than derived later: this is the one
+        // place that knows what "the version we picked" means, and
+        // recomputing the preference order at the render site would be
+        // a second copy of it.  `handleTracklistScopeChange` rebuilds
+        // through here too, so the switch does not read as a choice of
+        // version.
+        this.defaultVersionKey = this.selectedVersionKey;
     }
 
     /**
@@ -2297,9 +2516,11 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
                     entity-type="album"
                     @catalog-retry=${this.retryCatalog}
                 ></catalog-scope-notice>
-                ${this.renderVersionSelector()}
+                ${this.renderAutotagMatch()}
+                ${this.renderChosenVersion()}
                 ${this.renderTracklistScope()}
                 ${this.renderTracklist()}
+                ${this.renderVersionSelector()}
             </div>
             <track-details></track-details>
         `;
@@ -2950,26 +3171,230 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
 
     /* ── Version Selector (R025, R026, R027) ── */
 
+    /**
+     * "MusicBrainz has a match for this album."
+     *
+     * The complaint this answers is that the user had to notice the
+     * metadata was missing, then go and hunt the album down on the
+     * Autotag page — so the point is to say it *here*, while they are
+     * looking at the thing, with something to do about it.
+     *
+     * Three things about it are load-bearing.
+     *
+     * **Applying is offered only when it would do the whole album.** A
+     * tagging group is a folder, so a multi-disc album is several, and
+     * one button that applied to the best-scoring one would leave the
+     * album holding a mix of old and new tags — the exact case the
+     * app's Blocking notification level exists for. `groupCount` is
+     * the test, and the answer there is review, not apply.
+     *
+     * **The confirm is not a formality.** This rewrites tags on disk
+     * and cannot be undone, so it goes through `confirmAction()` with
+     * an impact line that says so in those words.
+     *
+     * **The banner does not claim a percentage.** The backend has a
+     * score and deliberately does not put it in the sentence: 0.95
+     * reads as a probability and is not one. What the user needs is
+     * which release it is, which is what the release title and artist
+     * are for.
+     */
+    private renderAutotagMatch() {
+        const match = this.autotagMatch;
+
+        if (!match) return nothing;
+
+        const wholeAlbum = match.groupCount === 1;
+
+        return html`
+            <div class="autotag-match" role="status">
+                <wa-icon name=${ICON_AUTOTAG} aria-hidden="true"></wa-icon>
+                <p class="autotag-match-text">
+                    MusicBrainz has a match for this album:
+                    <strong>${match.title}</strong>
+                    ${match.artistCredit ? html` by ${match.artistCredit}` : nothing}.
+                    ${wholeAlbum
+                        ? nothing
+                        : html`<span class="autotag-match-note"
+                              >It is filed as ${match.groupCount} folders here, so
+                              tagging it is a review rather than one
+                              step.</span
+                          >`}
+                </p>
+                <div class="autotag-match-actions">
+                    ${wholeAlbum
+                        ? html`<wa-button
+                              size="small"
+                              variant="brand"
+                              ?disabled=${this.applyingTags}
+                              @click=${this.onApplyAutotagMatch}
+                              >Apply tags</wa-button
+                          >`
+                        : nothing}
+                    <wa-button
+                        size="small"
+                        appearance="outlined"
+                        @click=${this.onReviewAutotagMatch}
+                        >Review in Autotag</wa-button
+                    >
+                </div>
+            </div>
+        `;
+    }
+
+    /** Hand the group over to the Autotag page and go there. */
+    private onReviewAutotagMatch = () => {
+        const match = this.autotagMatch;
+
+        if (!match) return;
+
+        this.dispatchEvent(
+            new CustomEvent('navigate', {
+                bubbles: true,
+                composed: true,
+                detail: { view: 'autotag', groupKey: match.groupKey },
+            }),
+        );
+    };
+
+    /**
+     * Apply the match, after asking.
+     *
+     * `ApplyAsync` is the registered-job path, so the work is visible
+     * in the jobs indicator and cancellable there like every other
+     * long-running operation — this page does not grow a second
+     * progress surface for it. What it does own is the *acknowledgement*
+     * that the request was accepted, because the button is here.
+     *
+     * The page is not refreshed on completion either: rewriting tags
+     * emits `TrackMetadataChanged`, which `library-store` answers by
+     * discarding every cached collection, and this page reloads from
+     * that like everything else.
+     */
+    private onApplyAutotagMatch = async () => {
+        const match = this.autotagMatch;
+
+        if (!match || this.applyingTags) return;
+
+        const ok = await confirmAction({
+            title: `Tag this album as “${match.title}”?`,
+            message:
+                `The ${match.trackCount} files of this album are rewritten to` +
+                ` match the MusicBrainz release${
+                    match.artistCredit ? ` by ${match.artistCredit}` : ''
+                }.`,
+            impact:
+                'This edits the tags in the files on disk and cannot be' +
+                ' undone. Nothing is moved or deleted.',
+            confirmLabel: 'Apply tags',
+        });
+
+        if (!ok) return;
+
+        this.applyingTags = true;
+
+        try {
+            await ApplyAsync(match.groupKey, match.releaseMbid);
+
+            // The suggestion has been acted on, so it stops being a
+            // suggestion immediately rather than sitting there inviting
+            // a second click while the job runs.
+            this.autotagMatch = null;
+
+            notificationStore.transient({
+                text: 'Tagging this album — progress is in the jobs indicator.',
+            });
+        } catch (err) {
+            console.error('[explore-album] autotag apply failed', err);
+
+            // Persistent rather than transient: the user asked for
+            // something that did not happen, and retrying is meaningful.
+            notificationStore.persistent({
+                text: describeError(
+                    err,
+                    'Those tags could not be applied.',
+                ),
+                tone: 'error',
+            });
+        } finally {
+            this.applyingTags = false;
+        }
+    };
+
+    /**
+     * Which pressing is on screen — said only when the user chose it.
+     *
+     * The selector is a disclosure below the tracklist now, so nothing
+     * above the list names the version it came from. That is right for
+     * the default, which is what the header already describes; it is
+     * wrong the moment someone picks a different one, because then the
+     * tracklist and the page disagree and the control that explains it
+     * is off the bottom of the screen.
+     *
+     * `defaultVersionKey` is the whole test. A quiet line that appears
+     * on every album would be the thing this issue removed, one size
+     * smaller.
+     */
+    private renderChosenVersion() {
+        if (this.loadingReleases || this.errorReleases) return nothing;
+        if (!this.selectedVersionKey) return nothing;
+        if (this.selectedVersionKey === this.defaultVersionKey) return nothing;
+
+        const current = this.currentVersion();
+
+        if (!current) return nothing;
+
+        return html`
+            <p class="chosen-version">
+                Showing <strong>${current.label}</strong> —
+                ${current.sublabel}.
+                <button
+                    type="button"
+                    class="chosen-version-reset"
+                    @click=${this.resetVersion}
+                >
+                    Use the default version
+                </button>
+            </p>
+        `;
+    }
+
+    /** Back to what `buildClusters` picked, without opening the panel. */
+    private resetVersion = () => {
+        if (!this.defaultVersionKey) return;
+
+        this.selectedVersionKey = this.defaultVersionKey;
+    };
+
+    /**
+     * "Other versions" — a disclosure, below the tracklist.
+     *
+     * Choosing which pressing you are looking at is an advanced,
+     * metadata-repair task, and it used to sit directly above the
+     * tracklist with a heading and a paragraph of prose explaining our
+     * clustering heuristic. It is not removed — matching the wrong
+     * release is a real problem and this is how it gets fixed — it is
+     * demoted (#17).
+     *
+     * Two things about the shape are load-bearing, and both are
+     * `config-section`'s rules rather than new ones. The header is a
+     * real `<button aria-expanded aria-controls>` inside the heading
+     * that names the section, so it is reachable by Tab and by heading
+     * navigation alike. And the body **renders unconditionally and is
+     * toggled with `hidden`**, because `aria-controls` has to name an
+     * element that is in the DOM.
+     *
+     * The loading and error states this used to own are gone rather
+     * than moved. Both were unguarded, so they took the primary slot on
+     * every album regardless of whether there was ever going to be a
+     * choice: the spinner said the same thing `renderTracklist` was
+     * already saying about the same fetch, and the error is the one
+     * `catalog-scope-notice` shows at the top of the page with a retry
+     * — every path that sets `errorReleases` also sets `catalogFailed`,
+     * which is the only route to `unavailable`. What the tracklist does
+     * with a failure is now the tracklist's own business.
+     */
     private renderVersionSelector() {
-        if (this.loadingReleases) {
-            return html`
-                <section>
-                    <h3 class="section-header">Versions</h3>
-                    <div class="section-loading">Loading releases\u2026</div>
-                </section>
-            `;
-        }
-        if (this.errorReleases) {
-            return html`
-                <section>
-                    <h3 class="section-header">Versions</h3>
-                    <div class="section-error">
-                        <wa-icon name="triangle-exclamation"></wa-icon>
-                        ${this.errorReleases}
-                    </div>
-                </section>
-            `;
-        }
+        if (this.loadingReleases || this.errorReleases) return nothing;
 
         // A dropdown is only a choice if the choices differ. Counting
         // *entries* is the wrong test: a release group routinely has
@@ -2980,7 +3405,9 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         //
         // Distinct *tracklists* is the real question, and it is already
         // computed: clusters are keyed by tracklist fingerprint.
-        if (this.distinctTracklistCount() <= 1) return nothing;
+        const choices = this.distinctTracklistCount();
+
+        if (choices <= 1) return nothing;
 
         const aggregateEntries = this.versionEntries.filter(
             (e) => e.group === 'aggregate',
@@ -2990,35 +3417,59 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
         );
 
         return html`
-            <div class="version-selector">
-                <div class="version-selector-row">
-                    <label for="version-select">Version</label>
-                    <select
-                        id="version-select"
-                        @change=${this.handleVersionChange}
-                        aria-label="Select release version"
+            <section class="versions">
+                <h3 class="versions-heading">
+                    <button
+                        type="button"
+                        class="versions-toggle"
+                        aria-expanded=${this.versionsOpen ? 'true' : 'false'}
+                        aria-controls="versions-body"
+                        @click=${this.toggleVersions}
                     >
-                        ${aggregateEntries.length > 0
-                            ? html`
-                                  <optgroup label="Aggregate">
-                                      ${aggregateEntries.map((e) =>
-                                          this.renderVersionOption(e),
-                                      )}
-                                  </optgroup>
-                              `
-                            : nothing}
-                        <optgroup label="Versions">
-                            ${clusterEntries.map((e) =>
-                                this.renderVersionOption(e),
-                            )}
-                        </optgroup>
-                    </select>
+                        <wa-icon name="chevron-down" aria-hidden="true"></wa-icon>
+                        Other versions of this album (${choices})
+                    </button>
+                </h3>
+                <div id="versions-body" ?hidden=${!this.versionsOpen}>
+                    <p class="versions-intro">
+                        A release group can have several pressings with
+                        different tracklists. Pick another if the one
+                        above does not match your copy.
+                    </p>
+                    <div class="version-selector">
+                        <div class="version-selector-row">
+                            <label for="version-select">Version</label>
+                            <select
+                                id="version-select"
+                                @change=${this.handleVersionChange}
+                            >
+                                ${aggregateEntries.length > 0
+                                    ? html`
+                                          <optgroup label="Aggregate">
+                                              ${aggregateEntries.map((e) =>
+                                                  this.renderVersionOption(e),
+                                              )}
+                                          </optgroup>
+                                      `
+                                    : nothing}
+                                <optgroup label="Versions">
+                                    ${clusterEntries.map((e) =>
+                                        this.renderVersionOption(e),
+                                    )}
+                                </optgroup>
+                            </select>
+                        </div>
+                        ${this.renderVersionMeta()}
+                    </div>
                 </div>
-                ${this.renderVersionMeta()}
-            </div>
+            </section>
         `;
     }
 
+    private toggleVersions = () => {
+        this.versionsOpen = !this.versionsOpen;
+    };
+
     /**
      * One option in the version list.
      *
@@ -3197,8 +3648,21 @@ export class ExploreAlbumDetails extends LitElement implements ContextMenuHost {
             `;
         }
         if (this.errorReleases) {
-            // Error already shown in version selector section
-            return nothing;
+            // The failure belongs to the list that is missing because
+            // of it. This used to return `nothing` and lean on the
+            // version selector's own error block to have said it, which
+            // is precisely the coupling that made demoting the selector
+            // a rewrite rather than a move: a control in a collapsed
+            // disclosure cannot be the page's error surface.
+            return html`
+                <section>
+                    <h3 class="sr-only">Tracklist</h3>
+                    <div class="section-error">
+                        <wa-icon name="triangle-exclamation"></wa-icon>
+                        ${this.errorReleases}
+                    </div>
+                </section>
+            `;
         }
         const current = this.currentVersion();
         if (!current) {

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

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

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

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

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

@@ -13,6 +13,7 @@ import {
     isQueueSourceNavigable,
     navigateToQueueSource,
 } from '@utils/queue-source-link';
+import { PHONE_QUERY } from '@utils/breakpoints';
 import { PlayerController } from '@store/controllers/player-controller';
 import { creditStore } from '@store/credit-store';
 import { QueueController } from '@store/controllers/queue-controller';
@@ -80,6 +81,19 @@ export class NowPlaying extends LitElement {
 
     private reduceMotionQuery?: MediaQueryList;
 
+    /**
+     * Phone width, from the shell's own breakpoint.
+     *
+     * This is in JS rather than in the stylesheet because what changes
+     * is the *content*, not its appearance: the title, artist and
+     * source render as plain text instead of as links, and no CSS rule
+     * can take a click handler off an element.
+     */
+    @state()
+    private phone = false;
+
+    private phoneQuery?: MediaQueryList;
+
     /** Whether each field is actively mid-scroll (class toggle). */
     @state()
     private titleScrolling = false;
@@ -341,6 +355,12 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = this.reduceMotionQuery?.matches ?? false;
         this.reduceMotionQuery?.addEventListener('change', this.handleReduceMotionChange);
 
+        // Same reasoning as above: looked up here, not at module load,
+        // so a test can install its own matchMedia first.
+        this.phoneQuery = window.matchMedia?.(PHONE_QUERY);
+        this.phone = this.phoneQuery?.matches ?? false;
+        this.phoneQuery?.addEventListener('change', this.handlePhoneChange);
+
         this.resizeObserver = new ResizeObserver(() => {
             this.geometryDirty = true;
             this.requestUpdate();
@@ -364,6 +384,7 @@ export class NowPlaying extends LitElement {
         this.attachDragListeners(false);
         window.removeEventListener(SCROLL_CHANGE_EVENT, this.handleScrollModeEvent);
         this.reduceMotionQuery?.removeEventListener('change', this.handleReduceMotionChange);
+        this.phoneQuery?.removeEventListener('change', this.handlePhoneChange);
         this.resizeObserver?.disconnect();
         this.stopScrollCycle('title');
         this.stopScrollCycle('artist');
@@ -488,7 +509,7 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleTitleMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('title')}
             >
-              <span class="scroll-content">${trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
+              <span class="scroll-content">${this.phone ? track.title : trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
             </span>
             <span
               class="track-artist ${artistScrolling ? 'will-scroll' : ''} ${this.artistScrolling ? 'scrolling' : ''}"
@@ -498,14 +519,15 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleArtistMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('artist')}
             >
-              <span class="scroll-content">${creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
+              <span class="scroll-content">${this.phone ? track.artist || 'Unknown Artist' : creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
             </span>
             ${describeQueueSource(this.queue.source)
                 ? html`
                   <span
-                    class="track-source ${isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
+                    class="track-source ${!this.phone && isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
                     data-testid="now-playing-source"
                     @click=${(e: MouseEvent) => {
+                        if (this.phone) return;
                         if (!isQueueSourceNavigable(this.queue.source)) return;
                         navigateToQueueSource(
                             e.currentTarget as EventTarget,
@@ -571,6 +593,10 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = e.matches;
     };
 
+    private handlePhoneChange = (e: MediaQueryListEvent): void => {
+        this.phone = e.matches;
+    };
+
     private shouldScroll(field: 'title' | 'artist'): boolean {
         const overflows = field === 'title' ? this.titleOverflows : this.artistOverflows;
 
@@ -606,6 +632,12 @@ export class NowPlaying extends LitElement {
             track?.artist ?? '',
             this.shouldScroll('title') ? '1' : '0',
             this.shouldScroll('artist') ? '1' : '0',
+            // Crossing the breakpoint swaps a link for a bare string,
+            // and a link is not guaranteed to measure the same as the
+            // text inside it. The marquee travels a distance read from
+            // that measurement, so this belongs in the key even though
+            // the words are identical either side.
+            this.phone ? '1' : '0',
         ].join('\u0000');
     }
 

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

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

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

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

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

@@ -72,6 +72,24 @@ const MIN_WIDTH = 200;
 const MAX_WIDTH = 500;
 const DEFAULT_WIDTH = 320;
 
+/**
+ * The narrowest main panel the queue is allowed to leave behind before
+ * it stops being a column and becomes an overlay (plan 018, issue #24).
+ *
+ * There is no cliff to derive this from, and pretending otherwise would
+ * be the more dishonest answer: the track list rescales its columns
+ * continuously (213px down to 124px between main widths of 900 and 544,
+ * with no row overflow at any of them) and the album grid steps 3
+ * columns to 2 without breaking. So this is a judgement, anchored at
+ * both ends — it keeps the *default* 1100px window inline, because an
+ * inline queue is a desktop affordance people choose and demoting the
+ * common case to an overlay would be a regression in feel; and it puts
+ * every case measured as broken on the overlay side, which is 900x600
+ * (main = 379px, where all three of the Playlists header's actions are
+ * clipped) and every phone width (main = 69px at 390, 0px at 320).
+ */
+const MAIN_PANEL_FLOOR = 480;
+
 @customElement('queue-panel')
 export class QueuePanel
     extends LitElement
@@ -85,6 +103,22 @@ export class QueuePanel
     @property({ type: Boolean, reflect: true })
     open = false;
 
+    /**
+     * Whether the panel is covering the content instead of sitting
+     * beside it. **Computed, never set by a caller** — it is reflected
+     * so the stylesheet and a spec can both read it.
+     *
+     * It is deliberately *not* a media query, which is the whole reason
+     * this is a property and not a `@media` block. The panel's width is
+     * user state: drag-resizable between MIN_WIDTH and MAX_WIDTH and
+     * persisted. A breakpoint at a fixed viewport width silently
+     * assumes the default 320, so it is wrong by up to 180px for a user
+     * who has widened the panel — in the direction that hurts, since a
+     * wider queue is exactly when the content can least afford it.
+     */
+    @property({ type: Boolean, reflect: true })
+    overlay = false;
+
     @state()
     private isDragging = false;
 
@@ -190,6 +224,19 @@ export class QueuePanel
     private panelWidth = DEFAULT_WIDTH;
     private scrollbarDragging = false;
 
+    /** Watches `.content-area`, which is the viewport minus the sidebar. */
+    private spaceObserver?: ResizeObserver;
+
+    /**
+     * What had focus when the overlay opened, so Escape and the scrim
+     * can give it back. Focus is only taken back if the panel had it —
+     * the same rule `MenuKeyboard` follows, for the same reason: the
+     * queue can also be closed by the button in the bottom bar, and
+     * yanking focus away from wherever the user actually is would be
+     * worse than leaving it.
+     */
+    private overlayOpener: HTMLElement | null = null;
+
     // _itemSize is an internal property applied via Object.assign in BaseLayout's
     // config setter. Setting it to match the actual fixed .track-item height (49px)
     // prevents lit-virtualizer's scroll error correction from fighting the native
@@ -265,6 +312,86 @@ export class QueuePanel
             border-left: 1px solid var(--yj-border-subtle, #333);
         }
 
+        /* ---------------------------------------------------------
+           Overlay mode (plan 018, #24).
+
+           In flow the panel takes its width *from the main panel*,
+           which is the reported bug: at 900x600 that left 379px and
+           clipped every action in the Playlists header, and at 320px
+           it left 0px — the content was not degraded but gone.
+
+           Here the host spans the whole content area instead and
+           stops being a layout participant, so the main panel keeps
+           its full width and the queue sits over it. The host itself
+           is transparent and click-through; the scrim and the panel
+           are what take pointer events. The containment drops paint,
+           which would otherwise clip the panel's own shadow.
+           --------------------------------------------------------- */
+        :host([overlay]) {
+            position: absolute;
+            inset: 0;
+            width: auto;
+            background-color: transparent;
+            overflow: visible;
+            pointer-events: none;
+            contain: layout style;
+            z-index: 20;
+        }
+
+        /* Closed, an overlay is not there at all. In flow the panel is
+           width: 0, which is its own way of saying this; absolutely
+           positioned there is no width to collapse. */
+        :host([overlay]:not([open])) {
+            display: none;
+        }
+
+        :host([overlay][open]) {
+            border-left: none;
+        }
+
+        :host([overlay]) .panel-content {
+            position: absolute;
+            top: 0;
+            right: 0;
+            bottom: 0;
+            width: var(--queue-width, ${unsafeCSS(DEFAULT_WIDTH)}px);
+            max-width: 100%;
+            box-sizing: border-box;
+            background-color: var(--yj-bg-surface, #212529);
+            border-left: 1px solid var(--yj-border-subtle, #333);
+            box-shadow: -8px 0 24px rgb(0 0 0 / 45%);
+            pointer-events: auto;
+        }
+
+        /* Dragging the edge of something that is already covering the
+           content answers a question nobody asked, and it is a
+           mouse-only affordance either way. */
+        :host([overlay]) .resize-handle {
+            display: none;
+        }
+
+        .scrim {
+            position: absolute;
+            inset: 0;
+            background-color: rgb(0 0 0 / 45%);
+            pointer-events: auto;
+            border: none;
+            padding: 0;
+            margin: 0;
+            cursor: pointer;
+        }
+
+        /* The phone gets the whole width: below 600 there is no
+           "beside" left to be, and this is the shape #55 turns into a
+           real screen. A media query inside a shadow root is answered
+           by the viewport, so the component states this itself rather
+           than the shell reaching in. */
+        @media (max-width: 599px) {
+            :host([overlay]) .panel-content {
+                width: 100%;
+            }
+        }
+
         .resize-handle {
             position: absolute;
             top: 0;
@@ -656,6 +783,20 @@ export class QueuePanel
             '--queue-width',
             `${this.panelWidth}px`,
         );
+
+        // The mode is a measurement, so it is observed rather than
+        // computed once: the parent is `.content-area`, whose width is
+        // the viewport minus the sidebar — including the sidebar's own
+        // collapse at 900px, which is what makes 900 the *worst*
+        // desktop width rather than the minimum.
+        this.updateOverlayMode();
+
+        if (this.parentElement) {
+            this.spaceObserver = new ResizeObserver(() =>
+                this.updateOverlayMode(),
+            );
+            this.spaceObserver.observe(this.parentElement);
+        }
         document.addEventListener(
             'mousemove',
             this.handleMouseMove,
@@ -690,6 +831,9 @@ export class QueuePanel
         super.disconnectedCallback();
         this.creditsUnsub?.();
         this.creditsUnsub = undefined;
+        this.spaceObserver?.disconnect();
+        this.spaceObserver = undefined;
+        document.removeEventListener('keydown', this.onOverlayKeydown);
         document.removeEventListener(
             'mousemove',
             this.handleMouseMove,
@@ -736,7 +880,79 @@ export class QueuePanel
         this.delegationAttached = false;
     }
 
+    /**
+     * Decide whether the queue can afford to be a column.
+     *
+     * The parent is `.content-area`, so its width is the viewport minus
+     * the sidebar and the sum already accounts for the sidebar's own
+     * collapse. It is stable across the panel's own open/closed state
+     * in both modes — in flow the panel is a child of that box, and as
+     * an overlay it is out of flow — so this cannot oscillate.
+     */
+    private updateOverlayMode = () => {
+        const available = this.parentElement?.clientWidth ?? 0;
+
+        // Before layout there is nothing to measure, and answering 0 by
+        // flipping to overlay would show the scrim for a frame.
+        if (available === 0) return;
+
+        this.overlay = available - this.panelWidth < MAIN_PANEL_FLOOR;
+    };
+
+    /**
+     * Escape closes a scrimmed overlay, which is the one keyboard rule
+     * every dialog in this app already follows.
+     *
+     * It is a document listener rather than a panel-scoped binding
+     * (`services/shortcut-scope.ts`) because it is not a *shortcut*: it
+     * is the dismissal of something covering the page, and it has to
+     * work while focus is still behind the scrim. It is attached only
+     * while the overlay is actually up and removed on close, so it is
+     * scoped to a state rather than being a permanent global. Nothing
+     * else binds Escape — the shortcut service only uses it to blur a
+     * text input.
+     */
+    private onOverlayKeydown = (e: KeyboardEvent) => {
+        if (e.key !== 'Escape' || !this.open || !this.overlay) return;
+
+        e.stopPropagation();
+        this.closeFromOverlay();
+    };
+
+    private closeFromOverlay = () => {
+        const hadFocus = this.contains(
+            document.activeElement as Node | null,
+        );
+
+        this.open = false;
+
+        if (hadFocus) {
+            const back =
+                this.overlayOpener ??
+                document.getElementById('queue-button');
+
+            back?.focus();
+        }
+
+        this.overlayOpener = null;
+    };
+
     override updated() {
+        // The overlay owns Escape only while it is up.
+        if (this.open && this.overlay) {
+            document.addEventListener('keydown', this.onOverlayKeydown);
+
+            this.overlayOpener ??=
+                document.activeElement instanceof HTMLElement &&
+                document.activeElement !== document.body
+                    ? document.activeElement
+                    : null;
+        } else {
+            document.removeEventListener('keydown', this.onOverlayKeydown);
+
+            if (!this.open) this.overlayOpener = null;
+        }
+
         // Closed, the panel is `width: 0` — which hides it from the eye
         // and from nobody else: its Clear and Add buttons still took tab
         // stops at x=1440 and were still read out (H-5).  `inert` is the
@@ -1631,6 +1847,11 @@ export class QueuePanel
             '--queue-width',
             `${clampedWidth}px`,
         );
+
+        // Widening the panel is one of the two ways the content can run
+        // out of room, and it is the way a viewport-width media query
+        // cannot see at all.
+        this.updateOverlayMode();
     };
 
     private handleMouseUp = () => {
@@ -1714,6 +1935,15 @@ export class QueuePanel
         const tracks = this.queue.tracks;
 
         return html`
+            ${this.overlay
+                ? html`<div
+                      class="scrim"
+                      part="scrim"
+                      data-testid="queue-scrim"
+                      aria-hidden="true"
+                      @click=${this.closeFromOverlay}
+                  ></div>`
+                : nothing}
             <div class="panel-content">
                 <div
                     class="resize-handle ${this.isDragging
@@ -1763,6 +1993,16 @@ export class QueuePanel
                                 name=${ICON_PLAYLIST}
                             ></wa-icon>
                         </button>
+                        ${this.overlay
+                            ? html`<button
+                                  class="header-action-button"
+                                  data-testid="queue-close"
+                                  aria-label="Close queue"
+                                  @click=${this.closeFromOverlay}
+                              >
+                                  <wa-icon name="xmark"></wa-icon>
+                              </button>`
+                            : nothing}
                     </div>
                 </div>
 

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

@@ -4,8 +4,10 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import { designTokens } from '../../styles/tokens.css';
 
 import type { DragActiveDetail } from '@utils/drag-controller';
+import { ActiveViewController } from '@store/controllers/active-view-controller';
 import {
     ICON_PLAYLIST,
+    ICON_AUTOTAG,
     ICON_REQUESTED,
 } from '@utils/icon-language';
 
@@ -158,11 +160,20 @@ export class AppSidebar extends LitElement {
     /** Delay in ms before a drag-hover triggers navigation. */
     private static readonly HOVER_NAV_DELAY = 600;
 
-    /** Home, because that is where `index.ts` now navigates on startup
-     *  (H-8). The sidebar does not hear a `navigate` it did not send,
-     *  so this default is what keeps `aria-current` honest on arrival. */
-    @state()
-    private activeView: View = 'home';
+    /**
+     * Which item is lit, read from the shell rather than tracked here.
+     *
+     * This used to be a `@state()` field defaulting to `home` -- the
+     * landing view -- because "the sidebar does not hear a `navigate`
+     * it did not send". That default was the only honest moment it
+     * ever had: a back-navigation dispatches no `navigate`, so the
+     * highlight stayed on the view the user had just left (#72), and
+     * the copy of this component that `bottom-nav` mounts inside its
+     * drawer opened on `home` from whatever page you were standing on.
+     * The shell publishes the active view now, so there is nothing to
+     * default and nothing to keep in step.
+     */
+    private activeCtrl = new ActiveViewController(this);
 
     @state()
     private isDragging = false;
@@ -208,7 +219,7 @@ export class AppSidebar extends LitElement {
         { id: 'tracks', label: 'Tracks', icon: 'music' },
         { id: 'explore', label: 'Explore', icon: 'globe' },
         { id: 'downloads', label: 'Downloads', icon: ICON_REQUESTED },
-        { id: 'autotag', label: 'Autotag', icon: 'tag' },
+        { id: 'autotag', label: 'Autotag', icon: ICON_AUTOTAG },
         { id: 'jobs', label: 'Jobs', icon: 'list-check' },
         { id: 'settings', label: 'Settings', icon: 'gear' },
     ];
@@ -236,10 +247,6 @@ export class AppSidebar extends LitElement {
             'yj-drag-active',
             this.onDragActive as EventListener,
         );
-        document.addEventListener(
-            'navigate',
-            this.onGlobalNavigate as EventListener,
-        );
     }
 
     override disconnectedCallback() {
@@ -261,10 +268,6 @@ export class AppSidebar extends LitElement {
             'yj-drag-active',
             this.onDragActive as EventListener,
         );
-        document.removeEventListener(
-            'navigate',
-            this.onGlobalNavigate as EventListener,
-        );
         this.clearDragHoverTimer();
     }
 
@@ -281,8 +284,9 @@ export class AppSidebar extends LitElement {
             <nav aria-label="Main">
             <ul>
                 ${this.navItems.map((item) => {
+            const active = this.activeCtrl.isActive(item.id);
             const classes = [
-                this.activeView === item.id
+                active
                     ? 'active'
                     : '',
                 this.dragHoverView === item.id
@@ -298,7 +302,7 @@ export class AppSidebar extends LitElement {
                                 type="button"
                                 class=${classes}
                                 data-testid="nav-${item.id}"
-                                aria-current=${this.activeView === item.id
+                                aria-current=${active
                     ? 'page'
                     : 'false'}
                                 @click=${() =>
@@ -381,19 +385,6 @@ export class AppSidebar extends LitElement {
     private static readonly DROP_VIEWS: Set<View> =
         new Set(['playlists']);
 
-    /** Keeps the highlighted nav item in sync with navigation that
-     * originates outside the sidebar itself (e.g. the launch-page
-     * dispatch in index.ts). */
-    private onGlobalNavigate = (
-        e: CustomEvent<{ view?: string }>,
-    ) => {
-        const view = e.detail.view;
-
-        if (view && this.navItems.some((item) => item.id === view)) {
-            this.activeView = view as View;
-        }
-    };
-
     private onDragActive = (
         e: CustomEvent<DragActiveDetail>,
     ) => {
@@ -459,7 +450,11 @@ export class AppSidebar extends LitElement {
     }
 
     private navigate(view: View) {
-        this.activeView = view;
+        // No optimistic highlight: the shell answers, and it answers
+        // synchronously in `handleNavigate` before it awaits anything.
+        // Setting it here as well is the second opinion this fix
+        // removes -- it is what let a click's highlight survive a
+        // navigation the shell then handled differently.
         this.dispatchEvent(new CustomEvent('navigate', {
             detail: { view },
             bubbles: true,

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

@@ -64,6 +64,7 @@ import { list } from '@utils/binding';
 import {
     ICON_PLAYLIST,
     ICON_QUEUE,
+    ICON_SMART_PLAYLIST,
 } from '@utils/icon-language';
 
 
@@ -1214,7 +1215,7 @@ export class SmartPlaylistDetails
                     <wa-icon name="arrow-left"></wa-icon>
                 </button>
                 <div class="playlist-avatar">
-                    <wa-icon name="filter"></wa-icon>
+                    <wa-icon name=${ICON_SMART_PLAYLIST}></wa-icon>
                 </div>
                 <div class="playlist-info">
                     <h1

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

@@ -11,6 +11,7 @@ import {
 import { SelectionController } from '@utils/selection-controller';
 import type { SelectionHost } from '@utils/selection-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
+import { PHONE_QUERY } from '@utils/breakpoints';
 import {
     ContextMenuController,
     contextMenuStyles,
@@ -105,9 +106,6 @@ const ROW_CHROME_WIDTH =
 const ROW_HEIGHT = 33;
 const PHONE_ROW_HEIGHT = 52;
 
-/** The shell's phone breakpoint, as `index.css` and every component
- *  stylesheet spells it. */
-const PHONE_QUERY = '(max-width: 599px)';
 
 // Inline SVG paths for favorite icons — eliminates wa-icon shadow DOM
 // overhead (30-50 shadow roots during scroll).  Font Awesome 6 paths.

frontend/src/icons/names.txt

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

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

@@ -400,6 +400,20 @@ async function dispatch(action: string): Promise<void> {
             break;
         }
 
+        // The keyboard half of #6. It dispatches the same events the
+        // header's buttons and the detail views' own back buttons do,
+        // rather than calling `history.back()` here: the shell owns the
+        // guard that stops a press at the root leaving the app, and a
+        // second caller reaching for `history` directly is how the old
+        // `navStack` came to disagree with the platform.
+        case 'nav.back':
+            document.dispatchEvent(new CustomEvent('navigate-back'));
+            break;
+
+        case 'nav.forward':
+            document.dispatchEvent(new CustomEvent('navigate-forward'));
+            break;
+
         case 'nav.queue': {
             const queuePanel = document.getElementById(
                 'queue-panel',

frontend/src/services/shortcut-meta.ts

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

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

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

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

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

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

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

frontend/src/store/history-store.ts

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

frontend/src/store/index.ts

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

frontend/src/utils/breakpoints.ts

@@ -0,0 +1,23 @@
+/**
+ * The shell's breakpoints, where JavaScript has to agree with CSS.
+ *
+ * A media query inside a shadow root is answered by the viewport, so a
+ * component normally states what it drops at phone width in its own
+ * stylesheet and needs nothing from here. This exists for the cases
+ * where the decision is not a style: `track-list` computes its grid in
+ * JS from the host width, and `now-playing` renders *different content*
+ * on a phone — a plain string instead of a link — which no stylesheet
+ * can express.
+ *
+ * One breakpoint, several expressions of it. It was a private const in
+ * track-list.ts when there was one; a second reader is where a copy
+ * would start drifting from index.css.
+ */
+
+/**
+ * Phone width. 600px rather than the sidebar's 900px because 900 is a
+ * laptop: the answer there is a narrower sidebar, which is still a
+ * sidebar. Below this the shell drops the sidebar column entirely and
+ * bottom-nav takes over.
+ */
+export const PHONE_QUERY = '(max-width: 599px)';

frontend/src/utils/icon-language.ts

@@ -54,6 +54,18 @@ export const ICON_PLAYLIST = 'list';
  */
 export const ICON_NEW = 'plus';
 
+/**
+ * A smart playlist — the rule, and the thing the rule makes.
+ *
+ * Governed for the reason `ICON_AUTOTAG` states: it was already at
+ * three call sites (the Playlists header, the row marker beside a smart
+ * playlist's name, and `smart-playlist-details`'s avatar), and a name
+ * stops being a detail of one component the moment there are two. It is
+ * deliberately *not* `ICON_NEW`, even on the button that makes one:
+ * an icon names the noun it acts on, and the noun here is the rule.
+ */
+export const ICON_SMART_PLAYLIST = 'filter';
+
 /**
  * The request ("want") toggle, as an outline/solid pair.
  *
@@ -80,6 +92,17 @@ export const ICON_REQUESTED = 'solid/bookmark';
  */
 export const ICON_IN_LIBRARY = 'check';
 
+/**
+ * The autotagger, and a match it is offering.
+ *
+ * The same icon as the Autotag destination in the sidebar, on the rule
+ * `ICON_PLAYLIST` was chosen by: an icon names the noun it acts on, so
+ * a suggestion on the album page wears the mark of the page it would
+ * send you to. Governed from the moment there were two call sites,
+ * which is when a name stops being a detail of one component.
+ */
+export const ICON_AUTOTAG = 'tag';
+
 /**
  * Something is being fetched right now.
  *
@@ -89,6 +112,18 @@ export const ICON_IN_LIBRARY = 'check';
  */
 export const ICON_DOWNLOADING = 'download';
 
+/**
+ * The rest of what this thing can do.
+ *
+ * `page-header` collapses the actions that do not fit into one menu
+ * behind this, so the glyph has to name *more of the same nouns* rather
+ * than any one of them — which is what an ellipsis is and what `bars`
+ * (the navigation drawer, one component over in `bottom-nav`) is not.
+ * It is deliberately the only meaning it carries: an overflow menu that
+ * shared an icon with a destination would be the `list` problem again.
+ */
+export const ICON_MORE_ACTIONS = 'ellipsis';
+
 /**
  * Take this away.
  *

frontend/test/components/album-autotag-match.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Being told about a match while looking at the album.
+ *
+ * The complaint (#28) is that the user had to notice their metadata
+ * was missing and then go and hunt the album down on the Autotag page.
+ * So the suggestion is drawn here, with something to do about it — and
+ * the something rewrites files on disk, which is what most of this
+ * file is about.
+ *
+ * The confidence tier behind "MusicBrainz has a match" is decided in
+ * the backend (`autotag.ConfidentTier`) so this page and strict
+ * auto-accept cannot disagree about what it means; what is pinned here
+ * is only what the page does with the answer.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+import { page } from 'vitest/browser';
+
+import '@components/explore-album-details/explore-album-details';
+import { stub, stubFailure, flush, resetHarness, calls } from '@test/support/harness';
+import { notificationStore } from '@store/notification-store';
+import '@components/notifications/notification-host';
+import { fixture, shadow, shadowAll } from '@test/support/render';
+
+const MATCH = 'autotagservice.Service.MatchForAlbum';
+const APPLY = 'autotagservice.Service.ApplyAsync';
+
+function match(over: Record<string, unknown> = {}) {
+  return {
+    groupKey: 'grp-1',
+    recommendation: 'strong',
+    score: 0.95,
+    releaseMbid: 'rel-1',
+    title: 'Glass Harbour',
+    artistCredit: 'Tideline',
+    trackCount: 10,
+    groupCount: 1,
+    ...over,
+  };
+}
+
+async function albumPage(): Promise<LitElement> {
+  const el = await fixture<LitElement>('explore-album-details', {
+    albumName: 'Glass Harbour',
+    localAlbumId: 7,
+  });
+
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+/** The confirm dialog attaches itself to the document on first use. */
+function confirmHost(): (LitElement & { shadowRoot: ShadowRoot | null }) | null {
+  return document.querySelector('confirm-dialog');
+}
+
+/** Press one of the dialog's own buttons, the way a person would. */
+async function pressConfirm(testid: string): Promise<void> {
+  const host = confirmHost();
+
+  if (!host) throw new Error('confirm-dialog did not mount itself');
+
+  await host.updateComplete;
+  host.shadowRoot
+    ?.querySelector<HTMLButtonElement>(`[data-testid="${testid}"]`)
+    ?.click();
+  await host.updateComplete;
+  await flush();
+}
+
+/** Click one of the banner's buttons by its label. */
+async function pressBanner(el: LitElement, label: string): Promise<void> {
+  shadowAll<HTMLElement>(el, '.autotag-match-actions wa-button')
+    .find((b) => b.textContent?.includes(label))
+    ?.click();
+  await flush();
+}
+
+beforeEach(() => {
+  resetHarness();
+  notificationStore.clear();
+  stub('explore.Service.BrowseReleases', []);
+  stub('explore.Service.LookupReleaseGroup', null);
+  stub('explore.Service.GetThumbnail', '');
+  stub('library.Library.GetAlbumTracks', []);
+  stub('library.Library.GetAlbumCompleteness', {
+    owned: 0,
+    expected: 0,
+    known: false,
+    complete: false,
+  });
+  stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+  stub('library.Library.GetFilePathsByRecordingMBIDs', {});
+  stub(MATCH, null);
+});
+
+describe('the autotag suggestion', () => {
+  it('says nothing when the backend has nothing confident', async () => {
+    const el = await albumPage();
+
+    expect(shadow(el, '.autotag-match')).toBeNull();
+  });
+
+  /**
+   * A pure catalog page has no files to retag, so the question is not
+   * asked at all — this runs on every album open and a call that
+   * cannot have an answer is a call not worth making.
+   */
+  it('is not even asked about an album with no local files', async () => {
+    stub(MATCH, match());
+
+    const el = await fixture<LitElement>('explore-album-details', {
+      albumName: 'Glass Harbour',
+      releaseGroupMBID: 'rg-1',
+    });
+
+    await flush();
+    await el.updateComplete;
+
+    expect(calls(MATCH)).toHaveLength(0);
+    expect(shadow(el, '.autotag-match')).toBeNull();
+  });
+
+  /**
+   * The banner names the release rather than quoting a number: 0.95
+   * reads as a probability and is not one, and which release it is, is
+   * the thing the user can actually judge.
+   */
+  it('names the release it is offering', async () => {
+    stub(MATCH, match());
+
+    const el = await albumPage();
+    const text = shadow(el, '.autotag-match')?.textContent ?? '';
+
+    expect(text).toContain('MusicBrainz has a match');
+    expect(text).toContain('Glass Harbour');
+    expect(text).toContain('Tideline');
+    expect(text).not.toContain('95');
+  });
+
+  it('offers both an apply and a review', async () => {
+    stub(MATCH, match());
+
+    await albumPage();
+
+    await expect
+      .element(page.getByRole('button', { name: 'Apply tags' }))
+      .toBeInTheDocument();
+    await expect
+      .element(page.getByRole('button', { name: 'Review in Autotag' }))
+      .toBeInTheDocument();
+  });
+
+  /**
+   * A tagging group is a folder, so a multi-disc album is several. One
+   * button that applied to the best-scoring one would leave the album
+   * holding a mix of old and new tags — which is the case the app's
+   * Blocking notification level exists for, and is worth not creating.
+   */
+  it('will not apply to an album filed as several folders', async () => {
+    stub(MATCH, match({ groupCount: 2 }));
+
+    const el = await albumPage();
+    const labels = shadowAll(el, '.autotag-match-actions wa-button').map(
+      (b) => b.textContent?.trim(),
+    );
+
+    expect(labels).toEqual(['Review in Autotag']);
+    expect(shadow(el, '.autotag-match')?.textContent).toContain('2 folders');
+  });
+
+  it('navigates to Autotag carrying the group key', async () => {
+    stub(MATCH, match());
+
+    const el = await albumPage();
+    const seen: CustomEvent[] = [];
+
+    el.addEventListener('navigate', (e) => seen.push(e as CustomEvent));
+
+    await pressBanner(el, 'Review');
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.detail).toMatchObject({
+      view: 'autotag',
+      groupKey: 'grp-1',
+    });
+  });
+});
+
+describe('applying from the album page', () => {
+  /**
+   * This rewrites tags in files on disk and cannot be undone, so it
+   * asks first — and cancelling has to be a true no-op, not a
+   * confirmation that fires the call anyway.
+   */
+  it('asks before it writes, and cancelling writes nothing', async () => {
+    stub(MATCH, match());
+    stub(APPLY, null);
+
+    const el = await albumPage();
+
+    await pressBanner(el, 'Apply');
+
+    expect(confirmHost()).not.toBeNull();
+    expect(calls(APPLY)).toHaveLength(0);
+
+    await pressConfirm('confirm-cancel');
+    await el.updateComplete;
+
+    expect(calls(APPLY)).toHaveLength(0);
+    expect(shadow(el, '.autotag-match')).not.toBeNull();
+  });
+
+  /**
+   * The impact line has to say the thing that cannot be taken back, in
+   * those words — "cannot be undone" — and that nothing is deleted,
+   * because "rewrites your files" reads worse than it is.
+   */
+  it('says what cannot be undone', async () => {
+    stub(MATCH, match());
+
+    const el = await albumPage();
+
+    await pressBanner(el, 'Apply');
+
+    const text = confirmHost()?.shadowRoot?.textContent ?? '';
+
+    expect(text).toContain('cannot be');
+    expect(text).toContain('undone');
+    expect(text.toLowerCase()).toContain('nothing is moved or deleted');
+  });
+
+  /**
+   * `ApplyAsync` is the registered-job path, so progress belongs to
+   * the jobs indicator and this page does not grow a second one. What
+   * it owes the user is an acknowledgement, because the button is
+   * here — and the suggestion has to stop inviting a second click.
+   */
+  it('hands the work to the job registry and stands down', async () => {
+    stub(MATCH, match());
+    stub(APPLY, null);
+
+    const el = await albumPage();
+
+    await pressBanner(el, 'Apply');
+    await pressConfirm('confirm-accept');
+    await el.updateComplete;
+
+    expect(calls(APPLY)).toHaveLength(1);
+    // The release is passed explicitly: a rescore between the page
+    // rendering and the click must not swap the album out from under
+    // a button the user has already read.
+    expect(calls(APPLY)[0]?.args).toEqual(['grp-1', 'rel-1']);
+    expect(shadow(el, '.autotag-match')).toBeNull();
+  });
+
+  /**
+   * A failure is Persistent, not Transient: the user asked for
+   * something that did not happen and retrying is meaningful, which is
+   * the notification store's own rule for choosing the level.
+   */
+  it('keeps a failure on screen', async () => {
+    stub(MATCH, match());
+    stubFailure(APPLY, 'the tag writer refused');
+
+    const el = await albumPage();
+
+    await pressBanner(el, 'Apply');
+    await pressConfirm('confirm-accept');
+    await el.updateComplete;
+
+    // Read it the way a person would: the app's one notification
+    // surface, rendered.
+    const host = await fixture<LitElement>('notification-host');
+
+    await host.updateComplete;
+
+    const shown = shadowAll(host, '[data-testid="notification"]').map(
+      (n) => n.textContent ?? '',
+    );
+
+    expect(shown.join(' ')).toContain('could not be');
+  });
+});

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

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

frontend/test/components/autotag-requested-folder.test.ts

@@ -0,0 +1,114 @@
+/**
+ * "Review in Autotag" has to land on *that* album.
+ *
+ * The album page can now say the autotagger has a match for what you
+ * are looking at (#28), and the review link is only worth having if it
+ * opens the same album. The queue is sorted by score, so the intended
+ * folder is often near the top — but "often" is a link that sometimes
+ * opens a different album, which is worse than no link.
+ *
+ * Autotag is a **cached primary view**: `index.ts` creates it once and
+ * reuses it, so there is no construction to pass a value to. The
+ * request arrives as an attribute, which is why the interesting part
+ * is that it is *consumed* — an attribute left on a cached element
+ * would reopen the same folder on every later visit to the page.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/autotag-view/autotag-view';
+import { flush, resetHarness, stub } from '@test/support/harness';
+import { fixture } from '@test/support/render';
+
+const FOLDERS = 'autotagservice.Service.ListPendingFolders';
+const CANDIDATES = 'autotagservice.Service.GetCandidates';
+
+function folder(groupKey: string, album: string) {
+  return {
+    groupKey,
+    libraryId: 0,
+    libraryName: 'Test',
+    folderSubPath: album,
+    trackCount: 10,
+    albumName: album,
+    albumArtist: 'Tideline',
+    discNumber: 0,
+    status: 'pending',
+    score: groupKey === 'grp-top' ? 0.99 : 0.5,
+    bestMatchReleaseMbid: 'rel-1',
+    synthetic: false,
+    likelyMixedBag: false,
+  };
+}
+
+/** Mount the view and run its activation, as navigation would. */
+async function autotag(groupKey?: string): Promise<LitElement> {
+  const el = await fixture<LitElement>('autotag-view');
+
+  if (groupKey !== undefined) el.setAttribute('group-key', groupKey);
+
+  (el as unknown as { onViewActivate: () => void }).onViewActivate();
+
+  await flush();
+  await el.updateComplete;
+  await flush();
+  await el.updateComplete;
+
+  return el;
+}
+
+/** The folder the view has selected. */
+function selected(el: LitElement): string | undefined {
+  return (el as unknown as { current?: { groupKey: string } }).current
+    ?.groupKey;
+}
+
+beforeEach(() => {
+  resetHarness();
+  stub('autotagservice.Service.StartAutotagQueue', null);
+  stub('autotagservice.Service.GetLocalCoverArt', '');
+  stub('autotagservice.Service.AckLibraryWarning', null);
+  stub('library.Library.GetAllLibrariesWithTrackCounts', []);
+  stub(FOLDERS, [folder('grp-top', 'Loudest Match'), folder('grp-asked', 'Glass Harbour')]);
+  stub(CANDIDATES, {
+    groupKey: 'grp-asked',
+    recommendation: 'strong',
+    localTracks: [],
+    candidates: [],
+    synthetic: false,
+    mixedBag: false,
+  });
+});
+
+describe('arriving at Autotag from an album page', () => {
+  it('opens the folder that was asked for, not the top of the queue', async () => {
+    const el = await autotag('grp-asked');
+
+    expect(selected(el)).toBe('grp-asked');
+  });
+
+  it('still lands on the best pending folder when nothing was asked', async () => {
+    const el = await autotag();
+
+    expect(selected(el)).toBe('grp-top');
+  });
+
+  /**
+   * The view is cached and never unmounts, so an attribute left behind
+   * is a standing instruction: every later visit to Autotag would
+   * reopen an album the user finished with three navigations ago.
+   */
+  it('consumes the request rather than remembering it', async () => {
+    const el = await autotag('grp-asked');
+
+    expect(el.hasAttribute('group-key')).toBe(false);
+
+    // A second visit, with no new request: whatever the user had
+    // selected stays selected.
+    (el as unknown as { onViewActivate: () => void }).onViewActivate();
+    await flush();
+    await el.updateComplete;
+
+    expect(selected(el)).toBe('grp-asked');
+  });
+});

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

@@ -3,15 +3,21 @@
  *
  * Three of these are about the thing that makes a second nav dangerous:
  * it has to agree with the first one. `bottom-nav` emits the same
- * bubbling, composed `navigate` event `app-sidebar` does and listens
- * for that event globally, so a navigation from anywhere — a card, a
- * detail view, the drawer's own sidebar — moves its highlight too. A
- * tab bar that only tracks its own clicks looks right until the moment
- * the user arrives somewhere by another route.
+ * bubbling, composed `navigate` event `app-sidebar` does, and reads
+ * which tab is lit from `activeViewStore` — the shell's one statement
+ * of where the user is — so it follows a navigation from anywhere: a
+ * card, a detail view, the drawer's own sidebar, or the back gesture.
+ *
+ * That last one is why the source is the store and not the `navigate`
+ * event these tests used to dispatch. `popstate` dispatches no
+ * `navigate` (index.ts calls `handleNavigate` directly), so a tab bar
+ * listening for the event looked right until the user pressed back —
+ * #72.
  */
 import { describe, expect, it, beforeEach } from 'vitest';
 
 import '@components/bottom-nav/bottom-nav';
+import { activeViewStore } from '@store/active-view-store';
 import type { BottomNav } from '@components/bottom-nav/bottom-nav';
 import { fixture, shadow, shadowAll, update } from '@test/support/render';
 import { resetHarness } from '@test/support/harness';
@@ -21,6 +27,12 @@ type Nav = BottomNav;
 const tabs = (el: HTMLElement) =>
   shadowAll<HTMLButtonElement>(el, 'nav button');
 
+/** The testids of whatever the bar says is the current page. */
+const current = (el: HTMLElement) =>
+  tabs(el)
+    .filter((b) => b.getAttribute('aria-current') === 'page')
+    .map((b) => b.dataset.testid);
+
 /** Resolve on one occurrence of an event, or reject loudly on time. */
 const once = (el: Element, name: string, timeoutMs = 2000) =>
   new Promise<void>((resolve, reject) => {
@@ -70,36 +82,55 @@ describe('bottom-nav', () => {
   it('follows a navigation it did not send', async () => {
     const el = await fixture<Nav>('bottom-nav');
 
-    document.dispatchEvent(new CustomEvent('navigate', {
-      detail: { view: 'tracks' },
-      bubbles: true,
-      composed: true,
-    }));
+    activeViewStore.setView('tracks', true);
     await update(el, {});
 
-    const current = tabs(el)
-      .filter((b) => b.getAttribute('aria-current') === 'page')
-      .map((b) => b.dataset.testid);
-
-    expect(current).toEqual(['tab-tracks']);
+    expect(current(el)).toEqual(['tab-tracks']);
   });
 
   it('marks exactly one tab current, and none for a view it has no tab for', async () => {
     const el = await fixture<Nav>('bottom-nav');
 
-    document.dispatchEvent(new CustomEvent('navigate', {
-      detail: { view: 'settings' },
-      bubbles: true,
-      composed: true,
-    }));
+    activeViewStore.setView('settings', true);
     await update(el, {});
 
     // Settings lives in the drawer, so nothing in the bar is current.
     // Leaving Home highlighted would be a tab bar lying about where
     // the user is.
-    expect(
-      tabs(el).filter((b) => b.getAttribute('aria-current') === 'page'),
-    ).toHaveLength(0);
+    expect(current(el)).toEqual([]);
+  });
+
+  it('keeps the parent tab lit while a detail view is open', async () => {
+    const el = await fixture<Nav>('bottom-nav');
+
+    activeViewStore.setView('albums', true);
+    // A detail view reports itself and is not primary, so it changes
+    // nothing. This is the first half of #72: the bar used to take the
+    // name, match it against no tab, and light nothing at all — while
+    // `app-sidebar`, which guarded on its own item list, kept the
+    // highlight. Neither was deliberate and the two disagreed.
+    activeViewStore.setView('explore-album-details', false);
+    await update(el, {});
+
+    expect(current(el)).toEqual(['tab-albums']);
+  });
+
+  it('follows the back path, which dispatches no navigate event', async () => {
+    const el = await fixture<Nav>('bottom-nav');
+
+    activeViewStore.setView('albums', true);
+    activeViewStore.setView('tracks', true);
+    await update(el, {});
+    expect(current(el)).toEqual(['tab-tracks']);
+
+    // What `popstate` does: the shell replays the entry through
+    // `handleNavigate` without dispatching `navigate`. A bar listening
+    // for the event stayed on Tracks — the view just left, confidently
+    // wrong rather than merely blank.
+    activeViewStore.setView('albums', true);
+    await update(el, {});
+
+    expect(current(el)).toEqual(['tab-albums']);
   });
 
   it('closes the drawer when a navigation happens', async () => {

frontend/test/components/chrome.test.ts

@@ -10,6 +10,7 @@ import '@components/sidebar/app-sidebar';
 import '@components/library-filter/library-filter';
 import '@components/library-status-indicator/library-status-indicator';
 import { Events } from '../../src/events';
+import { activeViewStore } from '@store/active-view-store';
 import { emit, stub, flush, calls, lastArgs } from '@test/support/harness';
 import {
   fixture,
@@ -49,6 +50,8 @@ describe('<app-sidebar>', () => {
   });
 
   it('marks exactly one item as the current page', async () => {
+    activeViewStore.setView('home', true);
+
     const el = await fixture('app-sidebar');
 
     const current = shadowAll(el, 'li button').filter(
@@ -72,17 +75,49 @@ describe('<app-sidebar>', () => {
     expect(seen).toEqual(['artists']);
   });
 
-  it('moves aria-current to the clicked destination', async () => {
+  it('moves aria-current with the shell, not with the click', async () => {
+    activeViewStore.setView('home', true);
+
     const el = await fixture('app-sidebar');
 
     shadow<HTMLElement>(el, '[data-testid="nav-genres"]')?.click();
     await el.updateComplete;
 
+    // The click asks; it does not answer. The sidebar used to move its
+    // own highlight optimistically, which is the second opinion #72
+    // removed -- one component deciding where the user is, while the
+    // shell decided separately and `bottom-nav` decided a third way.
+    expect(
+      shadow(el, '[data-testid="nav-genres"]')?.getAttribute('aria-current'),
+    ).toBe('false');
+
+    // What the shell does with that event, in one line.
+    activeViewStore.setView('genres', true);
+    await update(el, {});
+
     expect(
       shadow(el, '[data-testid="nav-genres"]')?.getAttribute('aria-current'),
     ).toBe('page');
   });
 
+  it('follows the back path, which dispatches no navigate event', async () => {
+    activeViewStore.setView('albums', true);
+
+    const el = await fixture('app-sidebar');
+
+    // `popstate` replays an entry through `handleNavigate` directly, so
+    // there is no `navigate` event to hear -- which is why the sidebar
+    // stayed on the view the user had just left (#72).
+    activeViewStore.setView('tracks', true);
+    await update(el, {});
+
+    expect(
+      shadowAll(el, 'li button')
+        .filter((item) => item.getAttribute('aria-current') === 'page')
+        .map((item) => item.getAttribute('data-testid')),
+    ).toEqual(['nav-tracks']);
+  });
+
   it('looks the way it did last time', async () => {
     const el = await fixture('app-sidebar');
 

frontend/test/components/confirm-dialog.test.ts

@@ -80,3 +80,42 @@ describe('confirmAction', () => {
     await expect(Promise.all([first, second])).resolves.toEqual([false, true]);
   });
 });
+
+/**
+ * A late `wa-hide` must not answer the next question.
+ *
+ * This is one singleton for every confirmation in the app, and
+ * `wa-dialog` reports its close *asynchronously* — `open = false`
+ * starts an animation and `wa-hide` arrives after it. So a hide
+ * belonging to a question already answered can land after the next one
+ * has opened: the user is asked something, the dialog vanishes on its
+ * own, and the call site is told they said no.
+ *
+ * Found by writing two `confirmAction()` tests in one file — the
+ * second could not be accepted at all, because the first one's hide
+ * had cancelled it before the click landed. In the app it needs two
+ * confirmations close together, which "apply these tags" now makes
+ * reachable.
+ */
+describe('two questions in a row', () => {
+  it('does not let the first one answer the second', async () => {
+    const first = confirmAction({ title: 'First?', message: 'One.' });
+
+    await press('confirm-cancel');
+    await expect(first).resolves.toBe(false);
+
+    const second = confirmAction({ title: 'Second?', message: 'Two.' });
+
+    // Whatever the first dialog's hide animation is still doing, the
+    // second question is on screen and unanswered.
+    await new Promise((r) => setTimeout(r, 0));
+
+    // The title is a `label` on `wa-dialog` and lands in *its* shadow
+    // root; the message is the part this component renders.
+    expect(host().shadowRoot?.textContent ?? '').toContain('Two.');
+
+    await press('confirm-accept');
+
+    await expect(second).resolves.toBe(true);
+  });
+});

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

@@ -7,6 +7,7 @@
  * opening it.
  */
 import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
 
 import '@components/home-view/home-view';
 import { stub, calls, lastArgs, stubFailure } from '@test/support/harness';
@@ -166,7 +167,17 @@ describe('home view', () => {
 
     const before = calls('home.Service.GetShelves').length;
 
-    shadow<HTMLElement>(el, 'wa-button')!.click();
+    // The action is declared to `page-header` rather than slotted as
+    // markup (#69), so it is a button in *that* shadow root now.
+    const header = shadow<HTMLElement>(el, 'page-header')!;
+
+    await (header as LitElement).updateComplete;
+
+    header.shadowRoot!
+      .querySelector<HTMLButtonElement>(
+        '[data-testid="page-action-shuffle-suggestions"]',
+      )!
+      .click();
     await el.updateComplete;
 
     expect(calls('home.Service.GetShelves').length).toBe(before + 1);

frontend/test/components/hover-affordance.test.ts

@@ -0,0 +1,85 @@
+/**
+ * A hover affordance is gated on the device having hover.
+ *
+ * The home page's cover cards reveal a play button on :hover. A touch
+ * long-press synthesises a hover state in the WebView, so on a phone
+ * that button flashed into view during the 500ms hold that
+ * utils/long-press.ts is measuring for a context menu — a control
+ * appearing because the user was reaching for a different one.
+ *
+ * This is asserted against the *parsed stylesheet* rather than by
+ * emulating a touch device, and that is a limitation worth stating
+ * rather than hiding. CDP's Emulation.setEmulatedMedia does not reach
+ * this tier's iframe — matchMedia still answers `hover: hover` after it
+ * is set — so there is no way here to render the component as a phone
+ * would and read the computed style. What can be checked is the shape
+ * the browser actually built from the css`` literal: that the reveal
+ * lives inside a hover media query and that the default is display:none.
+ *
+ * Which is the regression worth catching anyway. The failure mode is
+ * someone hoisting the rule back out of the query for a one-line tidy —
+ * a change nothing renders differently on a desktop, so every other
+ * assertion in this repo passes and the phone silently regresses.
+ */
+import { describe, expect, it } from 'vitest';
+
+import '@components/home-view/home-view';
+import { fixture } from '@test/support/render';
+
+/** Every rule in the element's own adopted stylesheets, flattened. */
+function rulesOf(host: Element): { text: string; condition: string | null }[] {
+  const sheets = host.shadowRoot?.adoptedStyleSheets ?? [];
+  const out: { text: string; condition: string | null }[] = [];
+
+  for (const sheet of sheets) {
+    for (const rule of Array.from(sheet.cssRules)) {
+      if (rule instanceof CSSMediaRule) {
+        for (const inner of Array.from(rule.cssRules)) {
+          out.push({ text: inner.cssText, condition: rule.conditionText });
+        }
+
+        continue;
+      }
+
+      out.push({ text: rule.cssText, condition: null });
+    }
+  }
+
+  return out;
+}
+
+describe('the home card play button', () => {
+  it('reveals itself only where the device has hover', async () => {
+    const el = await fixture('home-view', {});
+    const rules = rulesOf(el);
+
+    // The sweep is worth nothing if it read no rules at all — the same
+    // first assertion icon-language.test.ts makes for the same reason.
+    expect(rules.length).toBeGreaterThan(0);
+
+    const reveals = rules.filter(
+      (r) => r.text.includes('.play') && /opacity:\s*1/.test(r.text),
+    );
+
+    expect(reveals.length).toBeGreaterThan(0);
+
+    for (const rule of reveals) {
+      expect(rule.condition).toMatch(/hover:\s*hover/);
+      expect(rule.condition).toMatch(/pointer:\s*fine/);
+    }
+  });
+
+  it('is display:none rather than transparent where it is absent', async () => {
+    const el = await fixture('home-view', {});
+
+    // opacity:0 alone would leave a button that still takes taps and is
+    // still in the accessibility tree, so a phone would keep the hit
+    // area for a control it can never see.
+    const unconditional = rulesOf(el).filter(
+      (r) => r.condition === null && r.text.startsWith('.play'),
+    );
+
+    expect(unconditional.length).toBeGreaterThan(0);
+    expect(unconditional.some((r) => /display:\s*none/.test(r.text))).toBe(true);
+  });
+});

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

@@ -43,6 +43,9 @@ const GOVERNED = [
   'solid/bookmark',
   'regular/bookmark',
   'bars-staggered',
+  'tag',
+  'filter',
+  'ellipsis',
 ];
 
 /** The one file allowed to say them, plus its own test. */

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

@@ -0,0 +1,91 @@
+/**
+ * The global back/forward control (#6).
+ *
+ * The interesting half of this component is what it does when it
+ * *cannot* act. The app's rule is that a control which cannot do
+ * anything should not be a button at all — `library-status-indicator`
+ * spent a release as a `<button>` whose handler was a comment — and
+ * this is the documented exception: back and forward are a pair whose
+ * positions the user learns, so the unavailable one greys out rather
+ * than disappearing and moving the other one under the cursor.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import '@components/nav-history/nav-history';
+import { fixture, shadow, update } from '@test/support/render';
+import { historyStore } from '@store/history-store';
+
+const back = (el: HTMLElement) =>
+  shadow<HTMLButtonElement>(el, '[data-testid="history-back"]');
+
+const forward = (el: HTMLElement) =>
+  shadow<HTMLButtonElement>(el, '[data-testid="history-forward"]');
+
+describe('nav-history', () => {
+  beforeEach(() => {
+    historyStore.setDepth(false, false);
+  });
+
+  it('offers both directions, named', async () => {
+    const el = await fixture('nav-history');
+
+    // The name is the whole control: two arrows side by side are
+    // indistinguishable to anything not looking at them.
+    expect(back(el)?.getAttribute('aria-label')).toBe('Back');
+    expect(forward(el)?.getAttribute('aria-label')).toBe('Forward');
+  });
+
+  it('disables what cannot be done, in both directions independently', async () => {
+    const el = await fixture('nav-history');
+
+    expect(back(el)?.disabled).toBe(true);
+    expect(forward(el)?.disabled).toBe(true);
+
+    historyStore.setDepth(true, false);
+    await update(el, {});
+
+    expect(back(el)?.disabled).toBe(false);
+    expect(forward(el)?.disabled).toBe(true);
+
+    // Standing in the middle of the list, which is what a back press
+    // followed by a look at the toolbar produces.
+    historyStore.setDepth(true, true);
+    await update(el, {});
+
+    expect(back(el)?.disabled).toBe(false);
+    expect(forward(el)?.disabled).toBe(false);
+  });
+
+  it('asks the shell rather than reaching for history itself', async () => {
+    const el = await fixture('nav-history');
+    const seen: string[] = [];
+
+    for (const name of ['navigate-back', 'navigate-forward']) {
+      document.addEventListener(name, () => seen.push(name));
+    }
+
+    historyStore.setDepth(true, true);
+    await update(el, {});
+
+    back(el)?.click();
+    forward(el)?.click();
+
+    // Composed and bubbling, or index.ts's document listener — which
+    // owns the guard that stops a press at the root leaving the app —
+    // never hears them. A second caller reaching for `history`
+    // directly is how the old `navStack` came to disagree with the
+    // platform.
+    expect(seen).toEqual(['navigate-back', 'navigate-forward']);
+  });
+
+  it('says nothing when it cannot act', async () => {
+    const el = await fixture('nav-history');
+    const seen: string[] = [];
+
+    document.addEventListener('navigate-back', () => seen.push('back'));
+
+    back(el)?.click();
+
+    expect(seen).toEqual([]);
+  });
+});

frontend/test/components/now-playing-phone.test.ts

@@ -0,0 +1,166 @@
+/**
+ * The mini player's links are a desktop affordance.
+ *
+ * `utils/explore-link.ts` makes every track and artist name navigate,
+ * and `utils/queue-source-link.ts` makes "Playing from X" navigate — in
+ * the bottom bar those are a few characters of text at a font size
+ * chosen for a bar, which is not a touch target. Worse, explore-link
+ * holds the navigation for one double-click interval and drops it if a
+ * second click arrives: a gesture that exists so double-clicking a row
+ * can play it, and which means nothing at all on touch.
+ *
+ * So below the shell's phone breakpoint the three render as plain text
+ * and the whole bar's cover art opens the full-screen Now Playing view,
+ * which is where the links live.
+ *
+ * The breakpoint is stubbed rather than emulated for the reason
+ * track-list-phone.test.ts states: this tier's viewport is fixed at
+ * 1280x800 by the runner, and the component reads matchMedia in
+ * connectedCallback precisely so a test can answer it first.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+
+import '@components/now-playing/now-playing';
+import { Events } from '../../src/events';
+import { emit, flush } from '@test/support/harness';
+import { fixture, shadow, shadowAll, text } from '@test/support/render';
+import type { TrackInfo } from '@store/player-store';
+import type { QueueTrack } from '@store/queue-store';
+
+const TRACK: TrackInfo = {
+  fileName: 'ashes.mp3',
+  filePath: '/music/ashes.mp3',
+  trackLength: 215,
+  seekPosition: 0,
+  state: 'playing',
+  title: 'Ashes to Ashes',
+  artist: 'David Bowie',
+  album: 'Scary Monsters',
+  coverArt: '',
+  coverArtSmall: '',
+  coverArtMedium: '',
+  coverArtLarge: '',
+  trackChangeId: 1,
+  artistMbid: '',
+  releaseGroupMbid: '',
+  recordingMbid: '',
+};
+
+function queueTrack(n: number, title: string): QueueTrack {
+  return {
+    id: n,
+    audioFileId: n,
+    filePath: `/music/${n}.mp3`,
+    position: n,
+    title,
+    artist: 'David Bowie',
+    album: 'Scary Monsters',
+    coverArtPath: '',
+    artistMbid: '',
+    releaseGroupMbid: '',
+    recordingMbid: '',
+  };
+}
+
+/** Mount the bar with the phone breakpoint answering `matches`. */
+async function mountAt(phone: boolean) {
+  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;
+
+  try {
+    const el = await fixture('now-playing');
+
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 20 });
+    emit(Events.QueueChanged, {
+      tracks: [queueTrack(1, 'Ashes to Ashes')],
+      currentIndex: 0,
+      source: { type: 'album', id: 7, label: 'Scary Monsters' },
+    });
+    await flush();
+    await el.updateComplete;
+
+    return el;
+  } finally {
+    window.matchMedia = real;
+  }
+}
+
+describe('the mini player on a phone', () => {
+  beforeEach(() => {
+    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 1 });
+  });
+
+  it('renders the title and artist as plain text', async () => {
+    const el = await mountAt(true);
+
+    expect(shadowAll(el, '.explore-link').length).toBe(0);
+
+    // The words are unchanged — this is about what they are, not about
+    // hiding them. A fix that dropped the text would pass an assertion
+    // about links alone.
+    expect(text(el, '[data-testid="now-playing-title"]')).toContain(
+      'Ashes to Ashes',
+    );
+    expect(text(el, '[data-testid="now-playing-artist"]')).toContain(
+      'David Bowie',
+    );
+  });
+
+  it('does not navigate from the source line', async () => {
+    const el = await mountAt(true);
+    const source = shadow<HTMLElement>(el, '[data-testid="now-playing-source"]');
+
+    expect(source?.classList.contains('navigable')).toBe(false);
+
+    let navigated = false;
+    el.addEventListener('navigate', () => {
+      navigated = true;
+    });
+
+    source?.click();
+
+    expect(navigated).toBe(false);
+  });
+
+  it('still says where the queue came from', async () => {
+    const el = await mountAt(true);
+
+    // Dropping the *link* is the change; dropping the information would
+    // be a different and worse one.
+    expect(text(el, '[data-testid="now-playing-source"]')).toBe(
+      'Playing from Scary Monsters',
+    );
+  });
+
+  it('leaves the desktop bar exactly as it was', async () => {
+    const el = await mountAt(false);
+
+    expect(shadowAll(el, '.explore-link').length).toBeGreaterThan(0);
+
+    const source = shadow<HTMLElement>(el, '[data-testid="now-playing-source"]');
+
+    expect(source?.classList.contains('navigable')).toBe(true);
+
+    let detail: unknown;
+    el.addEventListener('navigate', (e) => {
+      detail = (e as CustomEvent).detail;
+    });
+
+    source?.click();
+
+    expect(detail).toEqual({
+      view: 'explore-album-details',
+      localAlbumId: 7,
+      albumName: 'Scary Monsters',
+    });
+  });
+});

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

@@ -9,7 +9,7 @@
  * the thing no assertion can — the header looking wrong.
  */
 import { describe, expect, it } from 'vitest';
-import type { PageHeader } from '@components/page-header/page-header';
+import type { PageAction, PageHeader } from '@components/page-header/page-header';
 
 import '@components/page-header/page-header';
 import { fixture, shadow, shadowAll, update, visual } from '@test/support/render';
@@ -19,6 +19,67 @@ const SORTS = [
   { id: 'tracks', label: 'Tracks' },
 ];
 
+/**
+ * Three actions of the shape that broke: Playlists' own, whose widths
+ * (91 + 122 + 162 = 390px) are what a 700px header could not hold.
+ */
+function playlistActions(seen: string[]): PageAction[] {
+  return [
+    {
+      id: 'import',
+      label: 'Import',
+      icon: 'file-import',
+      priority: 0,
+      onSelect: () => seen.push('import'),
+    },
+    {
+      id: 'new-playlist',
+      label: 'New Playlist',
+      icon: 'plus',
+      priority: 2,
+      onSelect: () => seen.push('new-playlist'),
+    },
+    {
+      id: 'new-smart-playlist',
+      label: 'New Smart Playlist',
+      icon: 'filter',
+      priority: 1,
+      onSelect: () => seen.push('new-smart-playlist'),
+    },
+  ];
+}
+
+/**
+ * Resize and let the fit settle.
+ *
+ * The rule is driven by a ResizeObserver, which delivers before paint
+ * and therefore after the microtask queue an `updateComplete` drains —
+ * so this waits on frames rather than on promises, and then on the
+ * render the measurement asks for.
+ */
+async function widthOf(el: PageHeader, px: number): Promise<void> {
+  el.style.width = `${px}px`;
+
+  for (let frame = 0; frame < 3; frame += 1) {
+    await new Promise((r) => requestAnimationFrame(r));
+    await el.updateComplete;
+  }
+}
+
+/** The labels currently rendered as buttons, in order. */
+function buttons(el: PageHeader): string[] {
+  return shadowAll<HTMLButtonElement>(el, '.action')
+    .filter((b) => !b.hidden)
+    .map((b) => b.textContent?.trim() ?? '');
+}
+
+/** The labels currently in the overflow menu, in order. */
+function menu(el: PageHeader): string[] {
+  return shadowAll(el, '#page-header-overflow wa-dropdown-item').map(
+    (i) => i.textContent?.trim() ?? '',
+  );
+}
+
 describe('<page-header>', () => {
   it('renders the heading as the page\u2019s only h1', async () => {
     const el = await fixture<PageHeader>('page-header', {
@@ -153,6 +214,264 @@ describe('<page-header>', () => {
   });
 });
 
+/**
+ * #69: Playlists slotted three buttons totalling 390px into a header
+ * that gets 700px at 900×600, and "New Smart Playlist" rendered 114 of
+ * its 162. It survived a spec named `layout-overflow` because that one
+ * asserts the *shell* needs no sideways scrolling — clipping inside a
+ * component is invisible to it.
+ *
+ * The header can only fix that for actions it renders itself, which is
+ * why they are data now. These are the assertions about the rule; the
+ * e2e spec is what checks it against the real widths.
+ */
+describe('<page-header> actions', () => {
+  it('renders a declared action, and asks the host to perform it', async () => {
+    // Same division the sort control already lives by: the header
+    // decides what fits, the host decides what happens.
+    const seen: string[] = [];
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      actions: playlistActions(seen),
+    });
+
+    await widthOf(el, 1200);
+
+    expect(buttons(el)).toEqual([
+      'Import',
+      'New Playlist',
+      'New Smart Playlist',
+    ]);
+
+    shadow<HTMLButtonElement>(el, '[data-testid="page-action-import"]')!.click();
+
+    expect(seen).toEqual(['import']);
+  });
+
+  it('hides the overflow trigger while everything fits', async () => {
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      actions: playlistActions([]),
+    });
+
+    await widthOf(el, 1200);
+
+    expect(shadow<HTMLButtonElement>(el, '.more-button')!.hidden).toBe(true);
+    expect(menu(el)).toEqual([]);
+  });
+
+  it('collapses the lowest priority first', async () => {
+    // Import is lowest because it is rarest; New Playlist is highest
+    // because it is the drop target, and a closed menu cannot be one.
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      count: 4,
+      countNoun: 'playlist',
+      sortOptions: SORTS,
+      sortField: 'name',
+      actions: playlistActions([]),
+    });
+
+    // Asserted as the *order* rather than at two chosen widths: which
+    // pixel drops which button depends on the font and on the shell
+    // this tier does not have, and pinning those numbers here would be
+    // a test of the fixture. What the host declares is a sequence.
+    const states: string[][] = [];
+
+    for (let width = 1200; width >= 300; width -= 40) {
+      await widthOf(el, width);
+
+      const now = menu(el);
+      const last = states[states.length - 1];
+
+      if (last === undefined || last.join() !== now.join()) states.push(now);
+    }
+
+    expect(states).toEqual([
+      [],
+      ['Import'],
+      ['Import', 'New Smart Playlist'],
+      ['Import', 'New Playlist', 'New Smart Playlist'],
+    ]);
+
+    // The menu lists them in the host's declared order, not in the
+    // order they happened to collapse — a menu that reshuffles itself
+    // as the window narrows is a menu nobody can learn.
+    expect(buttons(el)).toEqual([]);
+  });
+
+  it('gives an action back when the width returns', async () => {
+    // Every pass starts from all-visible, so the collapsed set is a
+    // function of the current width and not of how it got there. A rule
+    // that only ever added to the set would never widen again.
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      count: 4,
+      countNoun: 'playlist',
+      sortOptions: SORTS,
+      sortField: 'name',
+      actions: playlistActions([]),
+    });
+
+    await widthOf(el, 420);
+
+    expect(buttons(el)).toEqual([]);
+
+    await widthOf(el, 1200);
+
+    expect(menu(el)).toEqual([]);
+    expect(buttons(el)).toEqual([
+      'Import',
+      'New Playlist',
+      'New Smart Playlist',
+    ]);
+  });
+
+  it('collapses an action before it truncates the title', async () => {
+    // The title can ellipsis, which means `scrollWidth` reports a
+    // header that fits perfectly while the heading reads "Playlis…" —
+    // this issue's failure mode moved from the button to the title, and
+    // invisible to the same measurement that missed it the first time.
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      count: 4,
+      countNoun: 'playlist',
+      sortOptions: SORTS,
+      sortField: 'name',
+      actions: playlistActions([]),
+    });
+
+    await widthOf(el, 700);
+
+    const h1 = shadow<HTMLElement>(el, 'h1')!;
+
+    expect(h1.scrollWidth).toBeLessThanOrEqual(h1.clientWidth + 1);
+    expect(menu(el).length).toBeGreaterThan(0);
+  });
+
+  it('names the overflow trigger and says what it controls', async () => {
+    // An overflow menu is exactly the shape that grows a nameless
+    // control, and `aria-controls` cannot name an element that is not
+    // in the DOM — which is why the panel renders unconditionally and
+    // `wa-popup` hides it, the same rule `config-section` follows.
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      count: 4,
+      countNoun: 'playlist',
+      sortOptions: SORTS,
+      sortField: 'name',
+      actions: playlistActions([]),
+    });
+
+    await widthOf(el, 480);
+
+    const more = shadow<HTMLButtonElement>(el, '.more-button')!;
+
+    expect(more.hidden).toBe(false);
+    expect(more.getAttribute('aria-label')).toBe('More actions');
+    expect(more.getAttribute('aria-expanded')).toBe('false');
+    expect(more.getAttribute('aria-haspopup')).toBe('menu');
+
+    const panel = shadow<HTMLElement>(el, '#page-header-overflow')!;
+
+    expect(more.getAttribute('aria-controls')).toBe(panel.id);
+    expect(panel.getAttribute('role')).toBe('menu');
+
+    more.click();
+    await el.updateComplete;
+
+    expect(
+      shadow<HTMLButtonElement>(el, '.more-button')!.getAttribute(
+        'aria-expanded',
+      ),
+    ).toBe('true');
+  });
+
+  it('runs a collapsed action from the menu, and closes it', async () => {
+    const seen: string[] = [];
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      count: 4,
+      countNoun: 'playlist',
+      sortOptions: SORTS,
+      sortField: 'name',
+      actions: playlistActions(seen),
+    });
+
+    await widthOf(el, 700);
+    shadow<HTMLButtonElement>(el, '.more-button')!.click();
+    await el.updateComplete;
+
+    shadowAll<HTMLElement>(el, '#page-header-overflow wa-dropdown-item')[0]!.click();
+    await el.updateComplete;
+
+    expect(seen).toEqual(['import']);
+    expect(
+      shadow<HTMLButtonElement>(el, '.more-button')!.getAttribute(
+        'aria-expanded',
+      ),
+    ).toBe('false');
+  });
+
+  it('keeps a drop target a drop target, and does not fake one in the menu', async () => {
+    // You cannot drag a track onto a closed menu, so the affordance is
+    // absent from the overflow rather than approximated there. The
+    // header wires the handlers onto the button and owns none of them.
+    const dropped: string[] = [];
+    const actions: PageAction[] = [
+      {
+        id: 'new-playlist',
+        label: 'New Playlist',
+        icon: 'plus',
+        onSelect: () => undefined,
+        drop: {
+          active: true,
+          onDragOver: () => dropped.push('over'),
+          onDragLeave: () => dropped.push('leave'),
+          onDrop: () => dropped.push('drop'),
+        },
+      },
+    ];
+    const el = await fixture<PageHeader>('page-header', {
+      heading: 'Playlists',
+      actions,
+    });
+
+    await widthOf(el, 1200);
+
+    const button = shadow<HTMLElement>(
+      el,
+      '[data-testid="page-action-new-playlist"]',
+    )!;
+
+    expect(button.classList.contains('drag-over')).toBe(true);
+
+    button.dispatchEvent(new DragEvent('dragover', { bubbles: true }));
+    button.dispatchEvent(new DragEvent('drop', { bubbles: true }));
+
+    expect(dropped).toEqual(['over', 'drop']);
+
+    // …and collapsed, it is a menu item with no drop wiring at all.
+    await widthOf(el, 120);
+
+    expect(menu(el)).toEqual(['New Playlist']);
+    expect(
+      shadow<HTMLElement>(el, '[data-testid="page-action-new-playlist"]')
+        ?.hidden,
+    ).toBe(true);
+  });
+
+  it('renders nothing at all for a view with no actions', async () => {
+    // Two of the three hosts have one action and one has none while its
+    // other tab is up; an empty actions row is not a mode.
+    const el = await fixture<PageHeader>('page-header', { heading: 'Albums' });
+
+    await widthOf(el, 900);
+
+    expect(shadow(el, '.actions')).toBeNull();
+  });
+});
+
 describe('<page-header> as each view wears it', () => {
   // One baseline per arrangement rather than per view: the point is
   // that eight views produce four shapes, not eight.

frontend/test/components/queue-overlay-mode.test.ts

@@ -0,0 +1,175 @@
+/**
+ * #24 — the queue stops being a column when it cannot afford to be one.
+ *
+ * In flow the panel is `flex-shrink: 0`, so it takes its width *from
+ * the main panel* rather than covering it. Measured against the running
+ * app on the Playlists page, that left 379px of content at 900×600 —
+ * with all three of the page header's actions clipped — 69px at 390px
+ * wide, and **0px** at 320px, where the content was not degraded but
+ * gone.
+ *
+ * The rule is `available - panelWidth >= MAIN_PANEL_FLOOR`, and the
+ * reason it is a computed property rather than a `@media` block is the
+ * third test here: the panel's width is user state, drag-resizable
+ * between 200 and 500px and persisted, so a breakpoint on the viewport
+ * alone is wrong by up to 180px for a user who has widened it — in the
+ * direction that hurts, since a wider queue is exactly when the content
+ * can least afford it.
+ *
+ * The parent is `.content-area`, i.e. the viewport minus the sidebar,
+ * which is why these mount into a sized wrapper rather than into
+ * `document.body`: the width that decides this is the *parent's*, and
+ * `fixture()` would hand the panel the whole test window.
+ */
+import { describe, expect, it, afterEach } from 'vitest';
+
+import '@components/queue-panel/queue-panel';
+import type { QueuePanel } from '@components/queue-panel/queue-panel';
+import { shadow } from '@test/support/render';
+
+const wrappers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const w of wrappers.splice(0)) w.remove();
+});
+
+/**
+ * Mount a panel inside a parent of a stated width.
+ *
+ * The wrapper is `position: relative` and `display: flex` because that
+ * is what `.content-area` is; the mode is measured from
+ * `parentElement.clientWidth`, so a wrapper that collapses to its
+ * content would measure the panel rather than the space around it.
+ */
+async function panelIn(parentWidth: number): Promise<QueuePanel> {
+  const wrapper = document.createElement('div');
+
+  wrapper.style.cssText = `position: relative; display: flex; width: ${parentWidth}px;`;
+  document.body.append(wrapper);
+  wrappers.push(wrapper);
+
+  const el = document.createElement('queue-panel') as QueuePanel;
+
+  el.open = true;
+  wrapper.append(el);
+
+  await el.updateComplete;
+  await settle(el);
+
+  return el;
+}
+
+/**
+ * A ResizeObserver delivers on a frame, not a microtask, so the mode
+ * lands a frame after the width that decides it.
+ */
+async function settle(el: QueuePanel): Promise<void> {
+  for (let frame = 0; frame < 4; frame += 1) {
+    await new Promise((r) => {
+      requestAnimationFrame(() => r(null));
+    });
+    await el.updateComplete;
+  }
+}
+
+/** Drag the resize handle by `dx`, the way a user widens the panel. */
+async function dragHandleBy(el: QueuePanel, dx: number): Promise<void> {
+  const handle = shadow<HTMLElement>(el, '.resize-handle');
+  const startX = el.getBoundingClientRect().left;
+
+  if (!handle) throw new Error('no resize handle to drag');
+
+  handle.dispatchEvent(
+    new MouseEvent('mousedown', { clientX: startX, bubbles: true }),
+  );
+  document.dispatchEvent(
+    new MouseEvent('mousemove', { clientX: startX - dx, bubbles: true }),
+  );
+  document.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+
+  await settle(el);
+}
+
+describe('the queue panel decides whether it can be a column', () => {
+  it('stays inline while the content can spare the width', async () => {
+    const el = await panelIn(1080);
+
+    expect(el.overlay).toBe(false);
+    expect(el.hasAttribute('overlay')).toBe(false);
+  });
+
+  it('becomes an overlay when it cannot', async () => {
+    const el = await panelIn(700);
+
+    expect(el.overlay).toBe(true);
+    expect(el.hasAttribute('overlay')).toBe(true);
+  });
+
+  /**
+   * The test the media query could not have passed. The parent does not
+   * move; only the user's own panel width does.
+   */
+  it('flips to overlay when the user widens the panel, at a fixed width', async () => {
+    const el = await panelIn(880);
+
+    expect(el.overlay).toBe(false);
+
+    await dragHandleBy(el, 180);
+
+    expect(el.overlay).toBe(true);
+  });
+
+  it('gives an overlay a scrim and a named way out, and an inline panel neither', async () => {
+    const overlaid = await panelIn(700);
+
+    expect(shadow(overlaid, '.scrim')).toBeTruthy();
+
+    const close = shadow(overlaid, '[data-testid="queue-close"]');
+
+    expect(close?.getAttribute('aria-label')).toBe('Close queue');
+
+    const inline = await panelIn(1080);
+
+    expect(inline.shadowRoot?.querySelector('.scrim')).toBeNull();
+    expect(
+      inline.shadowRoot?.querySelector('[data-testid="queue-close"]'),
+    ).toBeNull();
+  });
+
+  it('closes on the scrim, on the close button and on Escape', async () => {
+    for (const close of [
+      (el: QueuePanel) => shadow<HTMLElement>(el, '.scrim')?.click(),
+      (el: QueuePanel) =>
+        shadow<HTMLElement>(el, '[data-testid="queue-close"]')?.click(),
+      () =>
+        document.dispatchEvent(
+          new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+        ),
+    ]) {
+      const el = await panelIn(700);
+
+      expect(el.open).toBe(true);
+
+      close(el);
+      await el.updateComplete;
+
+      expect(el.open).toBe(false);
+    }
+  });
+
+  /**
+   * Escape belongs to the overlay, not to the queue. An inline panel is
+   * beside the content rather than over it, so there is nothing to
+   * dismiss and the key has to reach whatever else wants it.
+   */
+  it('leaves Escape alone while inline', async () => {
+    const el = await panelIn(1080);
+
+    document.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+    );
+    await el.updateComplete;
+
+    expect(el.open).toBe(true);
+  });
+});

frontend/test/stores/view-stores.test.ts

@@ -1,11 +1,14 @@
 /**
- * The three small stores behind view chrome: the global search term,
- * the track list's column set, and the explore cache that keeps detail
- * pages from re-fetching what a search already returned.
+ * The small stores behind view chrome: the global search term, the
+ * active view both navs highlight, the track list's column set, and
+ * the explore cache that keeps detail pages from re-fetching what a
+ * search already returned.
  */
 import { describe, expect, it, beforeEach } from 'vitest';
 
 import { searchStore } from '@store/search-store';
+import { activeViewStore } from '@store/active-view-store';
+import { historyStore } from '@store/history-store';
 import { trackListStore } from '@store/tracklist-store';
 import { exploreCache, ARTIST_IMAGE_CACHE_LIMIT } from '@store/explore-cache';
 import { Events } from '../../src/events';
@@ -80,6 +83,97 @@ describe('search store', () => {
   });
 });
 
+describe('active view store', () => {
+  beforeEach(() => {
+    activeViewStore.setView('home', true);
+  });
+
+  it('holds the primary view the shell navigated to', () => {
+    activeViewStore.setView('albums', true);
+
+    expect(activeViewStore.get()).toBe('albums');
+    expect(activeViewStore.isActive('albums')).toBe(true);
+    expect(activeViewStore.isActive('tracks')).toBe(false);
+  });
+
+  it('leaves the primary view lit while a detail view is open', () => {
+    activeViewStore.setView('albums', true);
+    activeViewStore.setView('explore-album-details', false);
+
+    // #72's third finding, made deliberate: a detail view is not a
+    // destination in either nav, and the tab it was opened from is
+    // where the user still is. `app-sidebar` did this by accident (it
+    // guarded on its own item list) and `bottom-nav` did not do it at
+    // all, which is why one looked right and the other looked broken.
+    expect(activeViewStore.get()).toBe('albums');
+  });
+
+  it('does not notify when the view is unchanged', () => {
+    let notifications = 0;
+    const off = activeViewStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    activeViewStore.setView('albums', true);
+    activeViewStore.setView('albums', true);
+    activeViewStore.setView('explore-album-details', false);
+    off();
+
+    expect(notifications).toBe(1);
+  });
+
+  it('lights nothing for a view with no name', () => {
+    // The store starts empty rather than defaulting to a view, because
+    // a written-down default is right only while `GetDefaultPage()`
+    // agrees with it. That is only safe if the empty value matches
+    // nothing: `isActive` compares strings, and a component asking
+    // about an id it does not have must not light up.
+    activeViewStore.setView('', true);
+
+    expect(activeViewStore.isActive('')).toBe(false);
+  });
+});
+
+describe('history store', () => {
+  beforeEach(() => {
+    historyStore.setDepth(false, false);
+  });
+
+  it('holds both answers, because forward is not back negated', () => {
+    historyStore.setDepth(true, false);
+
+    expect(historyStore.get()).toEqual({ canBack: true, canForward: false });
+
+    // The middle of the list: both directions available at once, which
+    // a single depth counter cannot express and which is the state the
+    // old `pushedEntries` got wrong.
+    historyStore.setDepth(true, true);
+
+    expect(historyStore.get()).toEqual({ canBack: true, canForward: true });
+  });
+
+  it('does not notify when neither answer changed', () => {
+    let notifications = 0;
+    const off = historyStore.subscribe(() => {
+      notifications += 1;
+    });
+
+    historyStore.setDepth(true, true);
+    historyStore.setDepth(true, true);
+    off();
+
+    expect(notifications).toBe(1);
+  });
+
+  it('starts with both unavailable, which is the truth at launch', () => {
+    // A fresh session is one entry deep and that entry is *replaced*,
+    // not pushed, so there is nothing of ours behind it. A control
+    // that assumed otherwise would offer a press that does nothing --
+    // and on Android, one the OS would have used to exit the app.
+    expect(historyStore.get()).toEqual({ canBack: false, canForward: false });
+  });
+});
+
 describe('track list store', () => {
   it('starts from the default column set', () => {
     expect(trackListStore.getState().columnIds.length).toBeGreaterThan(0);

lefthook.yml

@@ -20,19 +20,14 @@ pre-commit:
       glob: "*.go"
       run: go tool golangci-lint run --timeout 5m ./...
 
+    # Snapshots the tree either side of the generators and reports only
+    # what moved across them.  This used to be `go generate` plus a bare
+    # `git diff --name-only`, which is the *whole unstaged worktree* — so
+    # any unrelated edit sitting there was reported as stale generated
+    # code, and `make generate` then fixed nothing.  See the script.
     codegen-check:
       glob: "*.{go,sql,templ}"
-      run: |
-        go generate ./...
-        if [ -n "$(git diff --name-only)" ]; then
-          echo "Generated code is out of date. Run 'make generate' and stage the changes."
-          # --no-pager, or this blocks forever on `less` waiting for a
-          # keypress that a hook run without a tty will never get: the
-          # commit hangs at exactly the moment it is trying to tell you
-          # why it failed.
-          git --no-pager diff --stat
-          exit 1
-        fi
+      run: ./scripts/codegen-check.sh
 
     # frontend/bindings is generated by `wails3`, not `go generate`, so
     # the check above does not cover it.  ~3.5s warm, ~20s on a cold
@@ -63,8 +58,17 @@ pre-commit:
       root: "frontend/"
       run: node scripts/check-css-literals.mjs
 
+# Deliberately sequential, unlike pre-commit.  `go test -race`
+# saturates every core for the better part of a minute and the UI tier
+# is a real browser with wall-clock timeouts, so run together the
+# browser loses: setup took 106s inside the hook against 63s
+# standalone, and a different suite failed each time -- three suites
+# failing to fetch setup.ts from Vitest's own dev server on one run, a
+# 15s "did not mount itself" on the next, against a suite that passes
+# 898/898 on its own. A gate that fails at random is not a gate. The
+# ~15s saved is not worth it.
 pre-push:
-  parallel: true
+  parallel: false
   commands:
     go-test:
       glob: "*.go"

scripts/codegen-check.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# Fails when `go generate ./...` would change something that is not staged.
+#
+# The obvious spelling of this is `go generate && git diff --name-only`,
+# which is what the hook used to be, and it answers the wrong question:
+# that diff is the *whole unstaged worktree*, so any unrelated edit — a
+# note, a plan document, the next commit's files sitting there while this
+# one lands — was reported as
+#
+#     Generated code is out of date. Run 'make generate' and stage the changes.
+#
+# Running `make generate` then does nothing, because nothing generated is
+# stale, and the message sends you looking for a codegen problem that does
+# not exist.  Splitting one piece of work into several commits is exactly
+# the shape that triggers it, so the workaround was a constraint on commit
+# order for no real reason.
+#
+# So the tree is snapshotted either side of the generators and only what
+# *moved across them* is reported.  That is deliberately not a list of
+# generated paths: sqlcgen, `*_templ.go` and `frontend/src/events.ts` are
+# today's answer, a fourth generator is one `//go:generate` line away, and
+# a path list is a second place to remember it — the same reasoning that
+# keeps staleshape.go parsing sql/schemas/ rather than restating it.
+#
+# Content, not names: a generated file that is *already* dirty and is then
+# rewritten further keeps its name in both snapshots and would otherwise
+# slip through.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# name + worktree blob hash for every file that differs from the index.
+# A file listed but absent (a deletion) hashes as "gone" rather than
+# aborting the pipeline.
+snapshot() {
+	git diff --name-only | while IFS= read -r f; do
+		if [ -f "$f" ]; then
+			printf '%s %s\n' "$f" "$(git hash-object -- "$f")"
+		else
+			printf '%s gone\n' "$f"
+		fi
+	done
+}
+
+# A brand-new generated file is not in either diff, because it is not
+# tracked at all — the same blind spot bindings-check.sh names.  Both
+# snapshots are taken before the generators run.
+before="$(snapshot)"
+before_untracked="$(git ls-files --others --exclude-standard)"
+
+go generate ./...
+
+after="$(snapshot)"
+after_untracked="$(git ls-files --others --exclude-standard)"
+
+# Symmetric difference, and the symmetry is the whole point.  Generation
+# can push a file *into* the unstaged set (it was current, now it is not)
+# or *out* of it (someone hand-edited generated output and the generator
+# put it back) — and the second is stale generated code just as much as
+# the first.  Comparing one direction only reports "current" for it,
+# which is the failure this script was written to stop.
+moved="$(comm -3 <(printf '%s\n' "$before" | sort) <(printf '%s\n' "$after" | sort) |
+	cut -d' ' -f1 | tr -d '\t' | sort -u | grep -v '^$' || true)"
+
+if [ -n "$moved" ]; then
+	echo "codegen-check: generated code is out of date." >&2
+	echo "Run 'make generate' and stage:" >&2
+	printf '  %s\n' $moved >&2
+	exit 1
+fi
+
+if [ "$after_untracked" != "$before_untracked" ]; then
+	echo "codegen-check: generation produced new files. Stage them:" >&2
+	comm -13 <(printf '%s\n' "$before_untracked" | sort) \
+		<(printf '%s\n' "$after_untracked" | sort) >&2
+	exit 1
+fi
+
+echo "codegen-check: generated code is current"

scripts/dev-headless.sh

@@ -97,6 +97,55 @@ if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
 fi
 rm -f "$PID_FILE"
 
+# ── Refuse to inherit somebody else's port ───────────────────────────
+# The PID check above only knows about *this* worktree: `make dev-stop`
+# kills the pid in this .dev/app.pid and nothing else.  Several worktrees
+# of this repo share the default port, so an app orphaned by a deleted
+# worktree goes on listening with nothing left to stop it.
+#
+# Without this check the new app starts, fails to bind, exits — and every
+# curl and playwright-cli call afterwards goes to the *other* process, so
+# the harness reports facts about an app nobody asked for.  That is not a
+# quiet wrongness either: it presented as
+# "no such table: libraries" against a freshly created YJ_HOME, which
+# reads exactly like applySchema or staleshape.go having gone wrong and
+# is a frightening place to start looking.
+#
+# The startup wait below cannot catch it, because the health check is
+# satisfied by *any* app on the port — which is precisely the failure.
+# So it is refused here, before anything is launched, rather than warned
+# about.  --port already exists for the legitimate second-app case.
+port_holder() {
+	command -v ss >/dev/null || return 0
+	ss -lptn "sport = :$PORT" 2>/dev/null | grep -oP 'pid=\K[0-9]+' | head -n 1
+}
+
+if curl -sf -o /dev/null --max-time 2 "http://localhost:$PORT/" ||
+	[ -n "$(port_holder)" ]; then
+	holder="$(port_holder)"
+	echo "dev-headless: :$PORT is already in use; refusing to start" >&2
+	if [ -n "$holder" ]; then
+		# /proc/<pid>/cwd names the checkout it belongs to, and says
+		# "(deleted)" for the orphaned-worktree case that is the whole
+		# reason this is worth a check.
+		cwd="$(readlink "/proc/$holder/cwd" 2>/dev/null || echo unknown)"
+		cmd="$(tr '\0' ' ' <"/proc/$holder/cmdline" 2>/dev/null || echo unknown)"
+		echo "  pid  $holder  ($cmd)" >&2
+		echo "  cwd  $cwd" >&2
+		# The PID-file check above has already passed, so whatever this
+		# is, `make dev-stop` does not know about it — saying otherwise
+		# sends you to a command that will report success and change
+		# nothing.  Never `pkill -f` here either: the pattern would
+		# match this script's own command line.
+		echo "  'make dev-stop' will not touch it (it is not in" >&2
+		echo "  ${PID_FILE#"$REPO_ROOT"/}): kill $holder, or pass --port." >&2
+	else
+		echo "  The holder could not be identified (no ss, or it belongs" >&2
+		echo "  to another user). Try: ss -lptn 'sport = :$PORT'" >&2
+	fi
+	exit 1
+fi
+
 # ── Choose the YJ_HOME ───────────────────────────────────────────────
 # A seed is a YJ_HOME that a previous run of the app produced, tarred
 # up (see scripts/seed-sandbox.sh).  Restoring it means starting *in*
@@ -200,6 +249,20 @@ until curl -sf -o /dev/null "http://localhost:$PORT/"; do
 	sleep 0.25
 done
 
+# The loop above exits on the first answer from the port, and "something
+# answered" is not "the app we started answered".  The pre-launch guard
+# makes that unlikely rather than impossible — a race, or a listener
+# started in between — and the check is one signal, so it is worth making
+# here too.  An empty log beside a dead pid is the "it exited immediately
+# and nothing said so" case that the original report spent its time on.
+if ! kill -0 "$APP_PID" 2>/dev/null; then
+	echo "dev-headless: :$PORT answered, but the app we started (pid" >&2
+	echo "  $APP_PID) is gone — something else holds the port." >&2
+	tail -n 30 "$LOG_FILE" >&2
+	rm -f "$PID_FILE"
+	exit 1
+fi
+
 cat <<EOF
 dev-headless: up
   url      http://localhost:$PORT

scripts/issue.sh

@@ -38,8 +38,10 @@
 # Where a body is taken and no --body-file is given, it is read from stdin.
 #
 # Environment:
-#   GITEA_TOKEN   a PAT with write:issue (plus write:repository and read:user,
-#                 which the rest of this repo's tooling reaches for)
+#   GITEA_TOKEN   a PAT with write:issue.  `claim` and `mine` additionally
+#                 need to know your username: set GITEA_USER, or give the
+#                 token read:user and it is looked up.
+#   GITEA_USER    your Gitea login.  Optional; see above.
 #   GITEA_URL     defaults to https://git.ljones.me
 #   GITEA_REPO    defaults to yonlu/yellowjacket
 set -euo pipefail
@@ -81,7 +83,29 @@ read_body() {
 	if [ "$file" = "-" ]; then cat; else cat "$file"; fi
 }
 
-me() { curl -sS -H "Authorization: token $GITEA_TOKEN" "$server/api/v1/user" | python3 "$py" login; }
+# The one lookup in this script that needs a scope beyond write:issue.
+# `GET /user` requires read:user, and it is reached for exactly two reasons:
+# to name the assignee in `claim`, and to filter in `mine`.  A token scoped to
+# the work this script does — write:issue — therefore failed at `claim`, which
+# is the one step the workflow requires before the first edit, so the whole
+# documented process was blocked by its own tooling.
+#
+# GITEA_USER short-circuits it, which is what lets a least-privilege token do
+# the job.  The lookup stays as the fallback because it is right when the
+# scope is there and needs no setup at all.
+me() {
+	if [ -n "${GITEA_USER:-}" ]; then
+		printf '%s' "$GITEA_USER"
+		return
+	fi
+	curl -sS -H "Authorization: token $GITEA_TOKEN" "$server/api/v1/user" |
+		python3 "$py" login ||
+		{
+			echo "issue.sh: could not resolve your username. Set GITEA_USER, or" >&2
+			echo "issue.sh: re-issue GITEA_TOKEN with read:user." >&2
+			exit 1
+		}
+}
 
 label_id() { call GET "/labels?limit=100" | python3 "$py" label-id "$1"; }