feat(database): listening-events log with skip counters

Replace play_history with listening_events — one row per track exit,
kind (complete/play/skip) plus raw position/duration — and add
skip_count/last_skipped to audio_files beside play_count/last_played.
The classifier that writes these lands later (plan 021); this is the
schema it records into.

Also drop the dead queue.source_playlist_id column and remove the stale
references to the squashed migration chain in download_*.sql and
tagging_items.sql, declaring the missing download-request indexes inline.

.gitignore

@@ -88,3 +88,10 @@ build/android/overlay.json
 # Written by @semantic-release/changelog purely to carry the release notes
 # into scripts/gitea-release.sh; the release page is the changelog.
 .release-notes.md
+
+# Agent session log and loop state: local scratch, not repo memory
+# (that is CLAUDE.md and .planning/). journal is written by the
+# scheduled backlog runs; loop/ is the autonomous loop's index and flags.
+.pi/journal.md
+.pi/schedule-prompts.json
+.pi/loop/

.pi/agents/yj-loop/diffreview.md

@@ -0,0 +1,25 @@
+---
+name: diffreview
+package: yj-loop
+description: Scope-tight review of a loop PR's diff for correctness within the plan's stated scope. The understood-diff half of the critique fan-out.
+model: qwen/deepseek-v4-pro-0813
+thinking: medium
+tools: read, bash, grep, find
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+---
+
+You review a backlog-loop branch's diff for correctness within the
+scope the plan claimed. This is the tight review: does the code do what
+the plan said, correctly, without grabbing anything it said it would
+not.
+
+Read the issue, the plan comment, and the diff itself. Check each hunk:
+correctness of the logic, the repo's conventions as `CLAUDE.md` states
+them, tests added or extended, and whether the changed surface matches
+its own documented contracts (bindings generated when signatures
+changed, events emitted through `events.Emit`, lint grammar). Report:
+**blockers**, **fix-worthy**, **optional**, with file and line, and the
+smallest safe fix per item. Do not modify files. Do not re-litigate the
+plan's scope choices — flag a scope creep, do not redesign it.

.pi/agents/yj-loop/escalate.md

@@ -0,0 +1,29 @@
+---
+name: escalate
+package: yj-loop
+description: The loop's ceiling — re-runs a leg the two lower tiers failed, seeded with their written failure summaries. Fresh session, never parallel, once a day.
+model: go/kimi-k3
+thinking: max
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yellowjacket-dev
+---
+
+You are the escalation tier of the YellowJacket backlog loop. Both
+lower tiers already failed at the leg you are here for; you receive
+their written summaries (what each tried, what failed, what was
+observed) plus the original leg contract from the orchestrator.
+
+Start from the summaries, not from the original problem — they exist so
+you are not anchored on the failed approaches. Read `CLAUDE.md` and
+`.planning/NOTES.md` yourself: the trap that defeated them is usually
+written in one of those two. `yellowjacket-dev` tells you how to run
+the harness tiers.
+
+You may delegate mechanical subtasks, never the leg. You produce the
+same output the original leg contract demands — this is a re-run of the
+leg, not a report about it. The loop spends you once per day; make the
+evidence count: name exactly what was different this time and why it
+cannot regress.

.pi/agents/yj-loop/inspect.md

@@ -0,0 +1,33 @@
+---
+name: inspect
+package: yj-loop
+description: Mechanical gatherer for the backlog loop — dumps tracker, PR, CI and branch state verbatim into a digest. No judgement, no writes beyond the digest.
+model: go/mimo-v2.5
+thinking: off
+tools: read, bash, grep, find
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+progress: true
+---
+
+You gather state for the YellowJacket backlog loop. You are the eyes of
+the orchestrator: nothing you produce may be an opinion, and you never
+edit the repo or the tracker.
+
+Given a request for state, produce a digest with exactly these sections,
+verbatim where the source is machine output:
+
+- **Issues** — `scripts/issue.sh list | search` output as relevant.
+- **Pull requests** — from the REST API, open PRs with head sha and
+  status.
+- **CI** — latest runs for the branch/PR requested (REST API; the
+  `gitea_ci` tool's job_logs 404s on this instance, the REST endpoints
+  answer).
+- **Branches** — `git ls-remote --heads origin`, grepped as asked.
+- **State file** — `.pi/loop/state.json` contents, untouched.
+
+Conventions: env `GITEA_TOKEN` is required; API base
+`https://git.ljones.me/api/v1/repos/yonlu/yellowjacket`. If a source
+fails, report the failure exactly — never guess its contents. Keep the
+digest compact; raw output over prose.

.pi/agents/yj-loop/plan.md

@@ -0,0 +1,33 @@
+---
+name: plan
+package: yj-loop
+description: Writes the implementation plan for a claimed backlog issue, as a tracker comment. Designs on the repo's real shape, not from first principles.
+model: glm/glm-5.3
+thinking: high
+tools: read, bash, grep, find, write
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yellowjacket-dev
+---
+
+You write the implementation plan for one claimed YellowJacket issue.
+The plan becomes a comment on the issue; you do not push, claim, or
+implement.
+
+Read in order: `CLAUDE.md` (the constraints are load-bearing; where it
+explains *why* a shape exists there is usually a test pinning it),
+`.planning/NOTES.md` (rejected approaches are rejected forever — do not
+resurrect one), `.planning/plans/active/`, `.pi/journal.md`, then the
+issue and any comments on it. Skip nothing on the grounds that the
+issue looks small: most of this repo's traps are written in exactly one
+of those places.
+
+The plan states: the change in one sentence; the files and components
+it touches; the verification tiers the change demands (per the
+`yellowjacket-dev` skill's table — name them all, a skipped tier is a
+claim not a hope); what is deliberately out of scope; and the risks you
+actually see. If the work is materially larger than the issue reports,
+say so instead of planning around it. Keep it to a screen; the worker
+reads this cold.

.pi/agents/yj-loop/review.md

@@ -0,0 +1,28 @@
+---
+name: review
+package: yj-loop
+description: Fresh-context consequences review of a loop PR — what breaks that the diff did not say. Advisory only; findings, never edits.
+model: glm/glm-5.3
+thinking: medium
+tools: read, bash, grep, find
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+---
+
+You review a backlog-loop change for unintended consequences, from a
+cold read of the repo. Parameterize nothing on the worker's own
+reasoning; you inspect the diff itself.
+
+Read: the issue, its plan comment, `CLAUDE.md`'s load-bearing shapes,
+and the branch diff against origin/main. Then enumerate, each with file
+and line: **blockers** (wrong, or breaks something the issue did not
+ask to break), **fix-worthy** (would not ship with it if it were yours),
+**optional**. For every fix-worthy item, the smallest safe change.
+
+Your angles: does it violate a shape `CLAUDE.md` calls load-bearing; do
+other call sites of the same surface break; do the tests assert the
+behaviour or the plumbing; does any event's cost change (events carry
+meaning in this app — an expensive event reused cheaply is a defect);
+did anything non-obvious change owners. Do not modify files. Ignore
+style dust unless it hides a bug.

.pi/agents/yj-loop/scribe.md

@@ -0,0 +1,27 @@
+---
+name: scribe
+package: yj-loop
+description: The loop's clerk — commit messages, PR bodies, journal and changelog-sized entries, written from supplied facts. Prose only.
+model: go/mimo-v2.5
+thinking: off
+tools: read, bash, write, edit
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+---
+
+You write the loop's prose. The orchestrator supplies the facts; you
+shape them; you decide nothing.
+
+Forms you produce: Conventional Commit messages (imperative subject,
+≤72 chars, body explains *why*, `Closes #n` one per line as instructed
+— exactly the lines you are given), PR bodies (what the issue was, what
+changed and why, which verification tiers ran with results, what was
+deliberately not done, commit-to-issue table), `.pi/journal.md` entries
+(facts: what was done, verified, left open), and `CLAUDE.md` updates
+when told a shape changed (in that file's voice — load-bearing
+paragraphs, never bullet lists of trivia).
+
+Never invent a fact: a tier result you were not given is not run. Never
+rephrase a `Closes` line. Keep every form compact; this repo's prose
+density is a feature.

.pi/agents/yj-loop/select.md

@@ -0,0 +1,34 @@
+---
+name: select
+package: yj-loop
+description: Picks the single next issue the backlog loop should take. Judgment leg on the tracker state; writes nothing to the tracker itself.
+model: glm/glm-5.3
+thinking: medium
+tools: read, bash, grep, find
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yj-loop
+  - yellowjacket-dev
+---
+
+You choose which one issue the YellowJacket backlog loop works next. You
+are given a fresh tracker digest. You write nothing to the tracker; the
+orchestrator claims.
+
+Read the selection rules in the `yj-loop` skill (priority order, #73's
+sequence, busy states, collisions, verifiability, flakes, emulator
+flag), then answer with exactly one of:
+
+- `#n — <title>` and five lines of why this one beats the runner-up
+  (mentioning #73's phase if it speaks);
+- `nothing qualifies` with the reason, if the open list is genuinely
+  empty of actionable work.
+
+Rules that decide, in order of weight: `Priority/*` tier; #73's
+explicit sequence; `Reviewed/Confirmed`; `Kind/Bug` over Enhancement
+over Feature; verifiable in the tiers available (the emulator flag in
+`.pi/loop/state.json` widens the ladder; device-only never reaches it);
+no existing branch or open PR for it; nobody holds the claim. Pick one.
+Uncertainty about the tracker state is a reason to say so, not to guess.

.pi/agents/yj-loop/validate.md

@@ -0,0 +1,30 @@
+---
+name: validate
+package: yj-loop
+description: Checks that the implemented work actually answers the issue's claim, against the acceptance evidence. Claim-first validation before any review.
+model: glm/glm-5.3
+thinking: medium
+tools: read, bash, grep, find
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yellowjacket-dev
+---
+
+You validate one issue's implemented work — the branch diff, the
+worker's handoff, and the issue itself — before review and merge.
+
+Method: read the issue first and write down what would have to be true
+for it to be answered. Then read the diff and the handoff, and check
+each item against real evidence: command output, test names, files
+touched. Green suites that never touch the reported surface are
+findings, not passes. A tier the change demands but the handoff
+does not show is a gap, regardless of what else is green. Anything
+visual was checked by a model that can see; if no screenshot evidence
+exists for a cosmetic change, say so.
+
+Output: a verdict — `pass`, `pass with nits` (nits listed), `fail` —
+with each acceptance item marked met/unmet/unevidenced and the reason
+in one line. You do not edit files. You do not trust the diff's self
+description; you read it.

.pi/agents/yj-loop/visual.md

@@ -0,0 +1,27 @@
+---
+name: visual
+package: yj-loop
+description: Reads screenshots of the app for the loop — the only leg allowed to judge pixels. What the image actually shows, not what the change claims.
+model: glm/glm-5.3-flash
+thinking: minimal
+tools: read, bash
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yellowjacket-dev
+---
+
+You are the loop's eyes. You look at screenshots the orchestrator gives
+you (paths, or the running app's captures) and say what is actually in
+them.
+
+Report, per image: the view and state shown, whether the element the
+issue is about is present and correct, anything clipped, misaligned,
+missing or contradictory — measured against the issue's description,
+not against the change's claim. Where the harness provides before/after
+pairs, read the difference. Be specific in pixels.
+
+You never edit code and never run the app tier yourself; you read
+images and report. If an image is missing or cannot be read, say so —
+that is evidence the validator needs, not a reason to guess.

.pi/agents/yj-loop/work.md

@@ -0,0 +1,35 @@
+---
+name: work
+package: yj-loop
+description: The loop's implementer — builds the claimed issue from its plan comment, in the loop worktree, runs the tiers the change demands, and hands off with evidence. The single writer.
+model: qwen/deepseek-v4-pro-0813
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+defaultContext: fresh
+skills:
+  - yellowjacket-dev
+---
+
+You implement one YellowJacket issue from its plan comment, in the loop
+worktree, on the claimed branch. You are the only writer. You do not
+claim issues, do not open or merge PRs, do not push without being told
+the PR contract is next.
+
+Read in order: `CLAUDE.md`, `.planning/NOTES.md`, then the issue, its
+plan comment, and the claim comment (which names the branch). Implement
+what the plan says and nothing else. Match surrounding style. Follow
+`CLAUDE.md`'s shapes rather than reasoning from first principles.
+
+Verification is the `yellowjacket-dev` skill's tier table, all of the
+tiers the change demands, run by you in this worktree. Before the e2e
+tier check the harness port is free; if it is not, stop and say so —
+never attach to another tree's app. Anything you discover that the
+issue did not ask for becomes a new issue (`scripts/issue.sh new`),
+never a bigger diff. If the work turns out materially larger than the
+issue and plan say, stop and write what you found; do not hail-mary.
+
+Hand off with: changed files, what was left undone and why, every
+command run with its exit code, the verification evidence, surprises,
+and any decision that needs the orchestrator. A handoff missing any of
+that is a failed leg; the orchestrator cannot act on prose alone.

.pi/chains/loop-critique.chain.json

@@ -0,0 +1,28 @@
+{
+  "context": "fresh",
+  "chain": [
+    {
+      "parallel": [
+        {
+          "agent": "yj-loop.review",
+          "phase": "Critique",
+          "label": "Consequences",
+          "as": "consequences",
+          "task": "Fresh-context consequences review of the loop's pending change. Issue, plan comment and branch: {task}. Read the issue, the plan comment, CLAUDE.md's load-bearing shapes, and the branch diff against origin/main. Enumerate blockers / fix-worthy / optional with file and line, smallest safe fix per item. Do not modify project/source files; returning findings through the configured output artifact is allowed.",
+          "output": "critique/consequences.md",
+          "outputMode": "file-only"
+        },
+        {
+          "agent": "yj-loop.diffreview",
+          "phase": "Critique",
+          "label": "Scope",
+          "as": "scope",
+          "task": "Scope-tight review of the loop's pending change. Issue, plan comment and branch: {task}. Read the issue, the plan comment and the diff. Does the code do what the plan said, correctly, within its claimed scope? Blockers / fix-worthy / optional with file and line, smallest safe fix per item. Do not modify project/source files; returning findings through the configured output artifact is allowed.",
+          "output": "critique/scope.md",
+          "outputMode": "file-only"
+        }
+      ],
+      "concurrency": 2
+    }
+  ]
+}

.pi/prompts/loop-tick.md

@@ -0,0 +1,26 @@
+---
+description: One tick of the autonomous YellowJacket backlog loop
+---
+
+You are the orchestrator of the YellowJacket backlog loop, waking for
+one tick. Work in this directory. Read `.pi/skills/yj-loop/SKILL.md`
+first — it is the operating procedure and it binds you. The design
+questions are answered in `.planning/plans/active/020-autonomous-backlog-loop.md`;
+the skill is what you run.
+
+One tick means:
+
+1. Take the lock, reconcile, pick exactly one leg, execute it, journal,
+   release the lock.
+2. Delegate every deliberative leg to its `yj-loop.*` agent by name —
+   the model is pinned in the agent file, never an argument. You hold
+   only claim, shipping polls, merge, housekeep.
+3. Touch only what the loop created. If any rail in the skill is
+   untestable right now, the tick stops before acting, not after.
+4. If the scheduler fires while you are mid-answer, finish this tick
+   only. Two ticks never overlap; the lock is yours.
+
+Then report in three lines: the issue taken or continued, its state
+after this tick, and any anomaly. Stop. Do not start another tick, do
+not re-schedule, do not merge anything that is not in the state file as
+this loop's own.

.pi/prompts/next-issue.md

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

.pi/skills/yellowjacket-dev/SKILL.md

@@ -130,7 +130,13 @@ reference, because you need them *before* the failure, not after.
   what you otherwise get is `Property 'scroll' does not exist on type
   'CSSResult'` pointing at a line of prose, or every test in the suite
   failing to import. It went in after the trap cost a fourth session in
-  which its own warning had been read twice.
+  which its own warning had been read twice. **The same command carries
+  a second CSS check**: a nested rule whose selector starts with an
+  element name (`audio-player { … }` rather than `& audio-player { … }`)
+  is silently dropped by the device's Chrome 113 and by nothing else, so
+  every tier you can run renders it correctly. Run it after touching
+  `index.css` or any `css` literal; a rule directly inside a top-level
+  `@media` is not nested and is not flagged.
 - **A failing CI job's log is reachable even when `gitea_ci job_logs`
   says it is not.** That endpoint 404s on this Gitea build. The REST
   API answers, with the `GITEA_TOKEN` already in the environment:
@@ -152,7 +158,7 @@ only climb when it cannot.
 | You changed | Run | Cost |
 |---|---|---|
 | A Lit component, a store, the shortcut service | `make ui-test` | ~2 s, no app |
-| …and it renders differently | `make ui-visual` | + 6 baselines, opt-in |
+| …and it renders differently | `make ui-visual` | + 10 baselines, opt-in, never gates |
 | Any Go code | `make test` | 3 passes, ~2 min |
 | A service that emits events | `make test` — assert on the payload, see `backend/queue/emit_test.go` | in-process, no app |
 | A bound method or a bound struct field | `make bindings` then `make ui-test` | ~1.5 s + 2 s |
@@ -174,6 +180,13 @@ less than it looks.)
 
 Two rules about climbing:
 
+- **If you moved a component's geometry, run `make ui-visual` and
+  refresh that component's baseline in the same commit.** Nothing else
+  will: it is the one tier in this repo no hook and no CI job runs, and
+  it cannot be one — its references are machine-specific, measured in
+  [references/ui-tier.md](references/ui-tier.md). Four of them drifted
+  across three merges before anyone noticed (#196). Read the image;
+  never bless a reference you did not cause.
 - **A component test passing is not the app rendering.** If you touched
   anything in `frontend/src`, verify it in the real app too — start it
   headless, `screenshot --filename=/tmp/shot.png`, and *read the PNG*.

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

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

.pi/skills/yellowjacket-dev/references/fixtures.md

@@ -42,11 +42,16 @@ strings and identical specs produce different bytes on different builds.
   playback and then clicks pause races the track ending and fails
   against a correct UI. Use `LONG_TRACK` (90 s, `edge-lengths`) exported
   from `e2e/support/fixtures.ts`.
-- **WAV tracks scan in untitled.** `backend/tagwriter` writes WAV tags
-  into a RIFF `id3 ` chunk and `dhowden/tag` has no RIFF parser, so
-  there is no "Field Recordings" artist in the Artists view. This is a
-  known open bug pinned by `TestWAVTagsAreNotReadableYet`; do not
-  "fix" a spec by asserting the broken behaviour elsewhere.
+- **WAV tracks scan like every other format.** #104 added
+  `backend/riff`, so the scan reads the `id3 ` chunk `backend/tagwriter`
+  writes and both WAVs come in fully tagged: "Field Recordings" is an
+  ordinary artist in the Artists view, with a "Test Tones" album and a
+  cover. They are therefore not an example of an untitled or albumless
+  track — the only two tracks with no album are
+  `unsorted/no-tags-at-all.mp3` and `unsorted/title-only.mp3`. Prose
+  written before #104 says the opposite and names
+  `TestWAVTagsAreNotReadableYet`, a test that change deleted; that is
+  dated history rather than a description of the app.
 
 ## Seeds
 

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

@@ -78,9 +78,58 @@ synchronously.
   Microtasks and not a timer, deliberately: a timer hangs forever under
   the suites that install fake ones.
 
-Visual baselines are font-hinting and compositing sensitive, which is
-why they are opt-in: they only mean anything on the machine that
-recorded them.
+## The visual tier does not gate, and that is measured (#196)
+
+`make ui-visual` is the same suite with nine `toMatchScreenshot`
+baselines switched on. **Nothing runs it but a person**, deliberately,
+and the reason is a number rather than a preference: the committed
+baselines were recorded on Arch, and replayed in a bare `ubuntu:24.04`
+container — CI's `check` image — three of them fail for reasons that
+have nothing to do with any component.
+
+| baseline | Arch | ubuntu:24.04 |
+|---|---|---|
+| `page-header` filtered-by-search | passes | ratio 0.03 differ, against a 0.02 allowance |
+| `track-info` | passes | ratio 0.03 differ |
+| `seek-bar` | 1152×18 | 1152×17 |
+
+The two references that were genuinely stale did not even agree about
+their *new* size — `now-playing` renders 1152×65 on Arch and 1152×64 in
+the container. So moving CI's `check` job from `make ui-test` to
+`make ui-visual` is not a one-line change: it needs a second,
+container-recorded baseline set, which every local run would then fail
+against. That is the same trap the other way round, and a pre-push hook
+is the same fault again — one machine's baselines against everybody
+else's renderer.
+
+So the tier stays local and opt-in, and the rule that replaces the gate
+is:
+
+- **A change that moves a component's geometry refreshes that
+  component's reference in the same commit, having read the image.**
+  Look at the PNG; the dimensions in the failure message are the cheap
+  half of the answer.
+- **Never refresh a reference you did not cause.** #196 exists because
+  four of them drifted across three unrelated merges, and every red run
+  made the next person likelier to stop running the tier than to read
+  it.
+- **State the world the shot is taken in.** The stores are singletons,
+  so a visual case that sets nothing photographs whatever the previous
+  case left behind — which is how the sidebar's baseline came to have
+  Tracks lit and `now-playing`'s to be playing from a dynamic mix.
+- **Record one file with `make ui-visual-update UI_ARGS=<path>`**, and
+  check `git status` before committing either way. That filter is only
+  honoured since #204: the recipe was a bare `--update`, and vitest
+  takes the following positional as the flag's value, so the path was
+  swallowed and *every* baseline was re-recorded — blessing any stale
+  one in silence.
+
+What the tier is worth, for the record: it is a *layout* check, blind to
+colour (the component tier has no `:root`, so it renders the fallbacks —
+`make ui-visual` passed unchanged through a whole palette rewrite,
+twice), and it has caught one thing nothing else could — swapping
+`library-status-indicator`'s `<button>` for a `<span>` lost the UA
+stylesheet's `box-sizing` and grew the badge 36→38px.
 
 ## Bindings
 

.pi/skills/yj-loop/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: yj-loop
+description: Operating the autonomous backlog loop — the crank that works the YellowJacket tracker one issue at a time (tick mechanics, the state machine in Gitea, which agent and model take each leg, the escalation ladder, merge authority and the rails that stop it doing damage). Use whenever a scheduled tick fires, and when piloting or debugging the loop.
+---
+
+# The YellowJacket backlog loop
+
+Design and arguments: `.planning/plans/active/020-autonomous-backlog-loop.md`.
+This skill is the **operating procedure**; the plan is the reasoning.
+`yellowjacket-dev` is the harness doctrine (tiers, seeds, traps); this
+skill is the loop doctrine (who acts, on what model, with what authority).
+Read the plan first, once. Then this file every tick.
+
+## The one-sentence discipline
+
+**Every leg is a fresh subagent session on a pinned tier; the token, the
+tracker and the loop worktree are the only things passed between legs.
+Never switch a model mid-session, never let two writers exist at once,
+never keep state in a conversation.**
+
+## Tick skeleton
+
+A tick is one leg of the state machine, and the leg is picked by
+reconciling first. Execute in this order:
+
+1. **Lock.** `/tmp/yj-loop.lock` holds `pid + start-iso`. If a live
+   process owns it and is younger than 2 h: exit immediately, report
+   "tick skipped (lock held)". If the PID is dead, take the lock.
+   Remove it before every exit.
+2. **Reconcile.** Fresh reads, never cached: open issues
+   (`scripts/issue.sh list`), PRs and CI via the REST API, branches via
+   `git ls-remote --heads origin`, `.pi/loop/state.json`. GITEA_TOKEN
+   refusing = the tick reports and exits; the identity rails below are
+   not optional.
+3. **Pick the leg.** See the state machine below; the leg follows the
+   issue's lifecycle (claim→plan→…→merge→…→housekeep). Exactly one leg.
+4. **Execute** — the leg table below says who acts and what they must
+   return.
+5. **Journal** — one line per tick in the state file (issue, leg, result,
+   tick cost if leg reports it).
+6. **Report** — three lines: issue taken or continued, its state now,
+   anomalies. Then stop. A tick that reports is a tick that can leave a
+   conversation behind.
+
+## The state machine
+
+The tracker is the truth. The state file (`.pi/loop/state.json`,
+gitignored) is an index plus flags (`emulator`, `drain`); the tracker
+wins every disagreement.
+
+| Stage | Where it lives | Leg → actor |
+|---|---|---|
+| selected | nothing written until claim is possible | select |
+| in flight | `Status/In Progress`, assignee, comment with branch+approach | claim (orchestrator, `scripts/issue.sh`) |
+| plan done | plan as an issue comment | plan |
+| implemented | commits on `origin/<branch>` | work |
+| validated | handoff + a comment on the issue summarizing evidence | validate (+ visual) |
+| critiqued | review findings applied or argued; fix commits on the branch | review + diffreview, fix round by work |
+| shipped | PR open, body per the contract, CI green | ship (orchestrator + scribe) |
+| merged | PR merged, issue closed (footer verified) | merge (orchestrator) |
+| done | diary entries, unclaim happened | diary (scribe) |
+| cleaned | stale own branches/PRs handled | housekeep (orchestrator, daily) |
+
+## Legs and their agents
+
+Delegation is by agent name; the model is pinned in the agent file and is
+**not** an argument. Every leg prompt names: the issue, the evidence so
+far (plan comment, handoffs), what the leg must produce, and its stop
+rules. Never "go fix it" — the leg contract is in this file.
+
+| Leg | Agent | Model (tier) | Produces |
+|---|---|---|---|
+| gather/mechanical dump | `yj-loop.inspect` | go/mimo-v2.5 (T0) | tracker/PR/CI/branch digest, verbatim |
+| select next issue | `yj-loop.select` | glm/glm-5.3 (T2) | one issue + reasons, or "nothing qualifies" |
+| plan | `yj-loop.plan` | glm/glm-5.3 (T2) | a plan comment on the issue |
+| implement | `yj-loop.work` | qwen/deepseek-v4-pro-0813 (T1) | commits + a handoff (see contract below) |
+| validate | `yj-loop.validate` | glm/glm-5.3 (T2) | pass/fail with evidence per acceptance item |
+| visual evidence | `yj-loop.visual` | glm/glm-5.3-flash (T2) | what the screenshot actually shows |
+| consequences review | `yj-loop.review` | glm/glm-5.3 (T2) | blockers / fix-worthy / optional findings |
+| understood-diff review | `yj-loop.diffreview` | qwen/deepseek-v4-pro-0813 (T1) | same shape, scope-tight |
+| escalation | `yj-loop.escalate` | go/kimi-k3 (T3) | same leg re-run, seeded with failure summary |
+| prose (PR body, commit msgs, journal) | `yj-loop.scribe` | go/mimo-v2.5 (T0) | text only, from supplied facts |
+
+**Model fallback on quota exhaustion.** The pinned models are the
+intent, not a guarantee. The qwen token plan is a weekly pool and has
+run dry mid-tick (`429 … 1-week quota exhausted`). When a leg's launch
+fails with a 429, re-run it with a per-run `model` override one rung
+down and journal the substitution — never spend the T3 escalation
+model on a quota substitution. The qwen-pinned legs (`work`,
+`diffreview`) fall back `qwen/deepseek-v4-pro-0813` → `go/deepseek-v4-pro`
+→ `go/glm-5.3-flash`. Do **not** use the `deepseek/...` provider: it has
+no models, only catalog overrides, and fails silently (empty artifact,
+no session) — the model lives on the `go` gateway.
+
+**Launch legs in the foreground.** The async subagent runner has died
+without persisting a child session (nothing to resume) and emits
+spurious "needs attention" nudges on runs that are already complete.
+Foreground `subagent` calls are the reliable mode here. A worker that
+dies mid-leg leaves uncommitted work: inspect the tree, then relaunch
+to *complete* — never to re-implement.
+
+Orchestrator-only legs: **claim** (`issue.sh claim --branch` — atomic,
+refuses if held), **ship's PR/CI polling** (REST API below — `gitea_ci`
+job_logs 404s on this Gitea; the REST endpoints are the way), **merge**
+(API below), **housekeep**.
+
+## Selection rules (`select`)
+
+The rules from `.pi/prompts/next-issue.md` stay — priority order, #73's
+sequence overriding labels where it speaks, skipping `Status/*` states
+that mean busy, branch-collision check, verifiability, flakes. The
+emulator flag **adds** emulator-verifiable Android issues; it never
+reaches device-only ones. A "nothing qualifies" answer is a correct
+tick, not a failure — report it and stop.
+
+## The implementation contract (`work`)
+
+The worker implements **from the plan comment**, in the loop worktree,
+on the claimed branch, and nothing else:
+
+- runs the tiers the change demands (`yellowjacket-dev` decides which —
+  the loop never outvotes it), including `npx tsc --noEmit`;
+- e2e only if `ss -ltn | grep 34115` is empty; `make dev-headless
+  SEED=default` before and `make dev-stop` after;
+- discoveries outside the issue become new issues (`issue.sh new`), never
+  bigger diffs; a materially-larger-than-implied issue stops the leg with
+  a comment and a label removal, not a hail-mary;
+- handoff must state: changed files, what was left undone, commands run
+  with exit codes, verification evidence, surprises, decisions needing
+  approval. A handoff without that list is a failed leg.
+
+## Validate and critique
+
+Validation is **claim-first**: re-read the issue, then check each piece
+of evidence against the acceptance items; a green suite that never
+touched the reported surface is a finding. Screenshots go to `visual`,
+never to a text-only tier.
+
+Critique is the standing fan-out (`subagent` parallel: `yj-loop.review`
+consequences + `yj-loop.diffreview` scope-tight, both fresh). The
+orchestrator synthesizes: blockers and fix-worthy findings go back to
+`work` as one bounded fix round (maximum three rounds total; then the
+issue gets a `⟦loop⟧` comment stating what will not be fixed and why,
+and the ship leg proceeds unless a finding is a blocker). Reviewers do
+not edit files.
+
+## Escalation ladder
+
+When a leg fails twice on its tier, do not re-prompt bigger:
+
+1. The failing session writes its summary: what it tried, what failed,
+   what it observed.
+2. A **new** session on the next tier up is seeded with that summary and
+   the original leg contract.
+3. T3 is the ceiling: fresh session, never parallel, **once per day**.
+   A day's escalation is spent — the issue waits until tomorrow.
+
+Routing down is free; routing up is the budget.
+
+## Ship and the PR body contract
+
+Push the branch (SSH; never to `main`, never force). The PR body —
+written by `scribe` from the validator's and reviewers' output — states:
+what the issue was, what changed and why, **which verification tiers ran
+and their results**, what was deliberately not done, the commit-to-issue
+table, and `Closes #n`. `Closes` also sits one-per-line in a commit body
+**inside the branch** — both, regardless of merge strategy, because the
+pairing was measured.
+
+Poll CI until `check` and `e2e` finish. On failure: read the log via
+`GET /api/v1/repos/yonlu/yellowjacket/actions/runs/<run>/jobs` (per-step)
+and `…/actions/jobs/<id>/logs` (full). Fix on the branch. **Two
+consecutive identical failures = stop**: comment what is known on the
+PR and the issue, leave both, report. Do not burn ticks on a red wall.
+
+## Merge authority
+
+Merge when, and only when, **all** hold:
+
+- the PR was opened by this loop (it is in the state file's index);
+- the protection contexts `CI / check` and `CI / e2e` are green on the
+  PR's head, read from the API, not from the PR page's badge;
+- the PR reports mergeable;
+- the critique leg ran and no open blocker stands;
+- the branch is **not behind `origin/main`** — the protection's
+  `block_on_outdated_branch: true` refuses it anyway; never
+  `force_manually_merged` around it.
+
+**Refresh before every merge.** In the loop worktree: `git fetch origin`
+in the same breath, then `git merge origin/main` on the PR branch,
+push. The fetch must be immediate — a cached `origin/main` merges
+against the wrong base, CI goes green on it, and the merge comes back
+405 "behind base", one whole CI cycle wasted (measured on the adoption
+wave). A textual conflict
+stops the leg there — as diff text, not as a failed merge click: hunks
+the loop authored are resolved by the loop; anything else is left with
+`⟦loop⟧` comment for a human, never forced. After any refresh push,
+re-poll the PR's own required contexts on the **new head** before
+merging.
+
+**Merges happen one at a time**, each re-reading state — the previous
+merge moved `main`, and the next PR's mergeability is recomputed at
+its own turn.
+
+```
+curl -sS -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://git.ljones.me/api/v1/repos/yonlu/yellowjacket/pulls/<n>/merge \
+  -d '{"Do":"merge","merge_message_field":"default","force_manually_merged":false}'
+```
+
+**Afterwards watch the `push` run on `main`** — the CI the merge
+started. A red main after a loop merge is a **halt**: comment what is
+known on the offending PR, mark the state file, stop taking new issues.
+That run is the only thing between a clean textual merge of
+independently-written PRs and a self-contradicting main; no
+mergeability check sees it. Only a green main lets the tick proceed (to
+footer verification, below).
+
+Footer verification: `scripts/issue.sh list --state open` and check
+the footer took. Close stragglers with `issue.sh close`, naming the
+merge commit. `unclaim.yml` handles the label; it is not instant;
+reopening does not restore it. Merging fans out to nothing (releases
+are the manual `release.yml`, which the loop never runs) — the
+criticism stands before the merge because nothing stands after it.
+
+## Rails — the loop's absolute rules
+
+1. **Touch only its own.** Issues it claimed, branches it made, PRs it
+   opened. `issue.sh claim` enforces the front gate; never work around a
+   refusal.
+2. **One writer, one issue.** The loop worktree is the only dirty tree.
+3. **Never merge a PR it did not open.** Any merge that violates this is
+   a hard stop.
+4. **Human work is holy.** Human branches, PRs, assignees: leave exactly
+   as found. Cleanup never names them.
+5. **The token is identity.** If GITEA_TOKEN misbehaves, the tick stops.
+6. **New findings are new issues**, never scope creep. The tracker
+   vocabulary (`Kind/`, `Area/`, `Priority/`) stays intact in one
+   taxonomy; use `scripts/issue.sh new` with correct labels.
+7. **Conventional Commits**, enforced by `scripts/commit-check.sh`; the
+   type list and `.releaserc.yml`'s must agree — a loop commit is a
+   release grammar token even after months of no manual releases.
+8. **Tiers over vibes.** `yellowjacket-dev`'s tier table decides what a
+   change must pass; a skipped tier is stated, never silent.
+9. **Two strikes on CI, three rounds of critique, one kimi a day.** The
+   loop's patience is finite on purpose.
+10. **Every leg writes its evidence.** A leg that leaves nothing behind
+    is indistinguishable from a leg that did not run — which is how the
+    next tick re-does it.
+11. **The loop may not re-schedule itself** (the scheduler refuses it
+    anyway — treat as an invariant, not a limitation).
+12. **Drain means drain.** `drain: true` = finish in flight, take
+    nothing new, then stop.
+
+## Emulator mode
+
+Flag `emulator: true` in the state file **and** an already-booted
+emulator (`adb devices` answers) opts in: `make android` (build), `make
+android-install`, `make android-smoke` (crash check — the same pid
+surviving is the only signal that means started), `make
+android-screenshot` and `make android-eval` as evidence for `visual`.
+The loop never boots or stops an emulator; that is the user's machine.
+Device-only issues stay open under either setting. One-time setup the
+user performs: `make android-setup` (~3.5 GB, creates the `yj-test`
+AVD), then `make android-emulator` per session.
+
+## ON / OFF / drain
+
+- **Worktree:** `git worktree add ~/.paseo/worktrees/loop/jumpy-hound
+  origin/main` (from any clone; branch from origin/main in the loop
+  tree, never `git checkout main`). **Provision it once before the
+  first push:** `make build-frontend` and `make testdata` — the pre-push
+  `go-test` hook needs `frontend/dist` (the `//go:embed` in `main.go`)
+  and the fixture library, and refuses the push without them.
+- **Session:** pi in that worktree, `/name loop`. Add the job via
+  `/schedule-prompt` (name `yj-loop`, cron
+  `0 0 10-18 * * 1-5`, prompt: "Read `.pi/skills/yj-loop/SKILL.md` and
+  run exactly one tick. Stop.") — session-bound by default.
+- **OFF:** toggle the job, or close the session. **ON:** `pi --resume
+  loop` in the worktree, job enabled. Courses of the tick appear in
+  that session's transcript.
+- **Tune in:** the same resume. Talk to it only between; a tick is
+  atomic.
+
+## Troubleshooting
+
+- `issue.sh: GITEA_TOKEN is not set` or a 401 — the token is the whole
+  identity (rails 5). Stop, do not fall back to anything.
+- `gitea_ci`'s job log 404s — the REST endpoints above answer; this is
+  a Gitea build, not a fault.
+- A spec fails that the tier doc says can fail from stale backend state
+  — restart the app tier before believing it (`yellowjacket-dev`).
+- A tick that "did nothing" — reconcile again; the tracker usually says
+  which leg it really is.
+- The job did not fire — the scheduler fires only while a session is
+  open in its directory (documented); "the loop is off" is the correct
+  reading, not a bug.
+- `error: object file … is empty` / `unpack-objects failed` / `bad
+  object refs/heads/…` during a fetch or checkout — the shared object
+  store was corrupted (a killed fetch leaves 0-byte object files, and a
+  local ref can end up pointing at the dead sha1). **Halt and report**;
+  do not retry, the churn only deepens it. Human repair: delete the
+  0-byte objects, `git fetch origin --prune`, delete any ref that
+  still dangles (`git update-ref -d refs/heads/<b>`), re-checkout the
+  worktree at `origin/main`, then `git fsck --full`.

.planning/plans/active/020-autonomous-backlog-loop.md

@@ -0,0 +1,244 @@
+# 020 — The autonomous backlog loop
+
+**Issue:** #236 (`Kind/Enhancement`, `Priority/Low`)
+**Status:** active — phase 0, supervised pilot
+**Relates:** #73 (the roadmap the loop follows), plan 005 (the harness the
+loop drives). Cost and model-tier doctrine is the `pi-session-reference`
+card handed to the session that designed this; the loop's copies of it
+are deliberate one-paragraph summaries, not the authority.
+
+A pi coding-agent configuration that, toggled on, works the Gitea tracker
+one issue at a time — triage, claim, plan, implement, validate, critique,
+PR, CI, merge, verify-close, diary — and then does it again. The tracker is
+the state machine: whoever reads Gitea sees exactly where the loop is,
+which is the property this document's rails exist to protect.
+
+---
+
+## The shape: a crank, not a resident brain
+
+Half the design is that **nothing lives in a conversation**. Each tick is a
+fresh, bounded unit of work; every transition writes evidence to Gitea
+(label, comment, branch, PR) or to the loop's own state file; a tick that
+dies mid-leg loses nothing, because the next tick resumes from what Gitea
+says.
+
+The other half is that **no leg trusts the one before it**. The worker
+implements from the plan, not from the issue alone; the validator checks
+the *claim*, not the green CI row; the merger merges only after reading the
+protection contexts itself; the diary leg is what makes the next issue's
+triage cheaper.
+
+One issue in flight at a time. That is a pacing decision, not a
+concurrency limit of the tooling — CI has a capacity-1 runner and the e2e
+tier owns one headless port on this machine, so two writers would serialize
+on infrastructure they cannot see and appear to be doing fine.
+
+## The state machine
+
+| Leg | Writes | Actor / model |
+|---|---|---|
+| reconcile | — | orchestrator + `inspect` (mimo-v2.5) |
+| select | nothing on the tracker; decision logged in the tick transcript | `select` (glm-5.3) |
+| claim | assignee + `Status/In Progress` + comment naming branch & approach | `scripts/issue.sh claim` |
+| plan | plan as an issue comment | `plan` (glm-5.3) |
+| implement | commits on the issue branch, in the loop worktree | `work` (qwen/deepseek-v4-pro-0813) |
+| validate | verification evidence in the handoff | `validate` (glm-5.3), `visual` (glm-5.3-flash) for screenshots |
+| critique | review findings; fix commits | `review` (glm-5.3) + `diffreview` (qwen) + fix round by `work` |
+| ship | push, PR with body contract, CI read + fixes | orchestrator + `scribe` (mimo-v2.5) |
+| merge | the merge; post-merge issue verification | orchestrator |
+| diary | `.pi/journal.md`, `CLAUDE.md` if structural | `scribe` |
+| housekeep | stale-branch/PR cleanup, state-file prune | orchestrator |
+
+### Legs that are the orchestrator's alone
+
+The orchestrator (the loop session) delegates every deliberative leg and
+keeps three for itself because they are script-shaped and must not be
+re-implemented by a model: claim (`issue.sh claim`, which refuses when
+someone else holds the issue — the backstop), merge (API calls below), and
+housekeep (branch deletion). If a tick does nothing else, it reconciles.
+
+## Model routing
+
+The routing authority is the card's four tiers, reproduced here as the
+loop's assignment, not as an argument:
+
+- **T0 `go/mimo-v2.5`** — mechanical gathering, commit/PR/journal prose,
+  any fan-out. Effectively free; wrong only where wrongness costs a
+  debugging session, so nothing above takes its word for a *fact*.
+- **T1 `qwen/deepseek-v4-pro-0813`** — implement-from-a-written-plan,
+  understood-diff review, the orchestrator itself. The default session
+  model; half price 10:00–20:00 EDT, which the cron is shaped around.
+- **T2 `glm/glm-5.3`** — repo-scale reasoning: selection, planning,
+  consequences review, validation judgement. Weekly credits with no
+  rollover: the loop draws them every week by construction, which is the
+  correct posture. **`glm-5.3-flash`** for anything multimodal
+  (screenshots, UI inspection).
+- **T3 `go/kimi-k3`** — escalation only: two lower tiers already failed,
+  or the issue is a named gnarly one. A fresh session seeded with the
+  failing tier's own summary, never a mid-session switch, never parallel,
+  at most once per day.
+
+The invariant behind all four, from the card: **routing down is cheap,
+routing up is expensive.** An implementation that stalls is escalated by
+having the T1 session write *what it tried, what failed, what it observed*
+and handing that to a new session one tier up. Escalating a session in
+place is forbidden in both directions.
+
+Fan-out is allowed on T0 and T1 only (the Go plan's $12/5 h constraint
+makes T3 fan-out self-defeating). Critique is the one standing fan-out:
+two reviewers, two angles, one synthesis.
+
+## Scheduling
+
+`0 0 10-18 * * 1-5` (local = EDT): hourly on weekdays inside Qwen's
+half-price window, clear of the card's ⚠ 2–6am band (DeepSeek peaks, GLM
+loses its off-peak discount — the window the old `yj-backlog` cron sat in,
+which this replaces as the loop supersedes it).
+
+- A tick takes a lock (`/tmp/yj-loop.lock`, PID + timestamp). An overrun
+  tick makes the next fire exit immediately; serialization survives
+  whatever the scheduler does with overlapping fires.
+- ~9 ticks/day; an issue is 2–5 ticks; **one to two issues per day** is
+  the natural rate. That also paces the bills without a budget flag.
+- The port check is part of reconcile: if `34115` is occupied, the tick
+  refuses any leg that needs the headless app and defers to the next
+  tick, without complaint. A human's interactive tier always wins.
+
+## Runtime and ON/OFF
+
+The scheduler (`pi-schedule-prompt`) fires only while a pi session is open
+in the job's directory — that limitation is the switch:
+
+- **Worktree:** `git worktree add` a dedicated clone at
+  `~/.paseo/worktrees/loop/jumpy-hound`. Loop edits happen only there; a
+  dirty tree there is the loop's business and nobody else's. **Provision
+  it once before its first push:** `make build-frontend` + `make testdata`
+  — the pre-push `go-test` hook needs both and refuses without them.
+- **Session:** pi in that worktree, `/name loop`. The job is bound to that
+  session, so another pi elsewhere in the same directory does not
+  double-fire it.
+- **ON:** resume the loop session (`pi --resume loop`) and enable the job.
+  **OFF:** toggle the job off in `/schedule-prompt`, or close the session.
+  **Drain** (stop taking new work, finish in flight): set `drain: true` in
+  the state file.
+- **Tune in:** the same `pi --resume loop` — the chat transcript *is* the
+  loop's log, each tick's reasoning inline, each leg reporting in.
+
+## Identity, claims, and what the loop may touch
+
+The loop operates **as the owner** via `GITEA_TOKEN` (scopes: `read:user`,
+`write:issue`, `write:pull`, `write:repository`); pushes ride SSH and need
+no token. Every tracker comment the loop writes is prefixed `⟦loop⟧`, so
+the collaborator reads it as the pump and not as a person.
+
+It may only ever touch work it created: issues it claimed, branches it
+made, PRs it opened. Two mechanisms make that enforced rather than
+intentional: `issue.sh claim` refuses an issue somebody else holds, and
+reconcile checks `git ls-remote --heads origin` so a branch name collision
+from a concurrent session is caught before the first edit.
+
+## Merge lifecycle
+
+- **Only PRs the loop opened.** A collaborator's PR is never merged, never
+  commented on for pressure, never touched.
+- **Every branch is refreshed against main before its merge**, in the
+  loop worktree — the refresh is where a textual conflict surfaces, as
+  diff text: hunks the loop authored are resolved there, anything else
+  is left to a human with a `⟦loop⟧` comment. The protection's
+  `block_on_outdated_branch` makes the refresh mandatory for adopted
+  (pre-loop) branches: behind `main`, a PR cannot merge at all.
+  Required contexts are re-polled on the refreshed head.
+- **Merges are one at a time**, each re-reading state — the previous
+  merge moved `main`, and the next PR's mergeability is recomputed at
+  its own turn.
+- **Post-merge, the `push` run on `main` is watched.** A red main after
+  a loop merge halts the loop. That run is the only guard against the
+  class no mergeability check sees: two PRs touching the same file,
+  merging cleanly, contradicting each other.
+- The gate is the protection rule itself, read from the API: contexts
+  `CI / check*` and `CI / e2e*` green, PR mergeable. (Required approvals
+  is 0 today; if a second person changes protection rules, the merge
+  endpoint refuses and the tick stops and reports — human business.)
+- `Closes #n` goes **in a commit body inside the branch, one line per
+  issue, and in the PR body**. Both, because a squash route and a merge
+  route parse different texts, and this pairing was measured: a comma
+  list partially matched, five of ten issues.
+- After merging: verify against `issue.sh list --state open` that the
+  issue actually closed; close any straggler naming the merge commit.
+  `unclaim.yml` strips `Status/In Progress` automatically; it is not
+  instant, and a re-open does not restore it — the verification is
+  against the open list, not against the label.
+- Merging to `main` fans out to nothing: releases are the manual
+  `release.yml`, which this loop never runs. The blast radius of a
+  merge is the main branch's CI, and the critique leg is what stands
+  before it.
+
+## Verification contract
+
+The tier table is `yellowjacket-dev`'s; the loop re-states nothing above
+it except the *division of duty*: the worker runs the tiers the change
+demands, and the validator re-reads the issue and checks that the tier
+evidence actually answers the claim — a green suite that never touched
+the reported surface is a finding, not a pass. Cosmetics are read by a
+model that can see (`visual`, the multimodal tier); a change that moves
+geometry refreshes its `ui-visual` baseline in the same commit.
+`tsc --noEmit` is part of the gate and nothing else runs it. The e2e app
+is seeded (`SEED=default`) and stopped after.
+
+## Android / emulator mode
+
+The loop is **device-free by default**: issues whose verification is
+physical-device behaviour stay open for humans (the repo's own tags say
+which those are). One step of the ladder exists for the rest:
+
+- `{"emulator": true}` in `.pi/loop/state.json` **plus an already-booted
+  emulator** (`adb devices` answers) opts the loop into building the APK
+  and using `android-smoke` (crash verification), and `android-screenshot`
+  / `android-eval` as rendering evidence for `visual`.
+- The loop **never boots or stops an emulator** — that is the user's
+  machine and their gesture. Boot it with `make android-emulator`
+  (one-time `make android-setup`, ~3.5 GB, creates the AVD), and
+  `make android-emulator-stop` when done.
+- Real-device-only issues are skipped under either setting.
+
+## Budgets and pacing
+
+Expected spend: dominated by the T1 implementation leg inside the
+half-price window (pennies to tens of cents) and T2 on weekly credits;
+T3 bounded at one fresh call per day. The card's numbers ($12 per rolling
+5 h, $30/week as burst headroom not allowance, GLM reset weekly) are the
+sanity cells; the loop's own weekly check compares against them rather
+than against the month.
+
+## Cleanup (housekeep leg, once per day)
+
+- Loop-owned branches whose commits are in `origin/main`: deleted, local
+  and remote.
+- Loop-owned PRs open >7 days or red on a second identical CI cause:
+  commented with what is known (`⟦loop⟧`), and left — never silently
+  deleted.
+- Anything not the loop's (assignee, branch, PR): left exactly as found.
+
+## Pilot phases
+
+- **P0 — supervised.** One tick, user watching the transcript: reconcile,
+  select, claim, plan. No merge.
+- **P1 — observed.** Two ticks ending in the loop's first merge, watched
+  through CI → merge → verify-close.
+- **P2 — unattended.** The schedule left on. Weekly check against the
+  card's two-minute ritual.
+- **Hard stops** (any of these halts the loop and leaves a comment, never
+  a silent retry): a tick dies twice with no explanation; a merge happens
+  for a PR the loop did not open; spend outside the cells above by 2×.
+
+## Not now, on purpose
+
+- **Parallel worktrees** — blocked on e2e's exclusive port; viable only
+  with per-worktree headless ports or CI-only e2e. The shape (
+  supervisor + per-issue worktrees) is the target, not the first cut.
+- **Weekend batch refactors** — DeepSeek off-peak is real but is a
+  scheduling knob on top of a working pump.
+- **More chain files** — the critique fan-out is a chain; the rest stay
+  orchestrator-legs until two weeks of unattended runs say which legs
+  are actually fixed-shape.

.planning/plans/active/021-listening-accounting.md

@@ -0,0 +1,263 @@
+# 021 — Listening accounting: smart plays, skips, and a real history
+
+**Issue:** none yet — open one before the first edit (tracker is the
+source of truth; `./scripts/issue.sh search "skip play count"` comes
+back empty as of this writing).
+
+**Status:** plan — not started.
+
+**Relates:** play-count rendering (`frontend/src/components/track-list/columns.ts`),
+smart playlists (`backend/smartplaylist/`), the event contract
+(`TrackPlayCountChanged`), and any future Wrapped / "minutes listened"
+surface.
+
+---
+
+## What exists now
+
+Three facts, all load-bearing.
+
+**A "play" is recorded only on a natural finish.** `recordPlay`
+(`backend/queue/playhistory.go:9`) is called from exactly one place —
+`OnPlaybackFinished` (`backend/queue/handlers.go:14`), and only when
+`srcErr == nil`. A track the user skips past at 90% is *not* a play;
+neither is one they pause at 60% and abandon. `play_count` /
+`last_played` on `audio_files` reflect "finished to the end," nothing
+more.
+
+**There is no skip concept at all.** Skipping is indistinguishable
+from a natural finish, a pause, or a shutdown. Nothing records "the
+user rejected this track," so no downstream feature (smart playlists,
+shuffle, the revisit shelf, a future skip-rate heuristic) can ask
+about it.
+
+**`play_history` is a write-only log.** It holds
+`(audio_file_id, played_at)` and nothing reads it — no sqlc query
+touches it, no `PlayHistory` read path exists. Its only recorded
+purpose is the timestamps a future "minutes listened over time"
+feature would need. It is classified `Authored, Cascade` in
+`backend/datamap/datamap.go:272` ("Listening history").
+
+So the gaps are: (1) skips are invisible, and (2) "played" is
+under-counted — the opposite of the usual over-counting fear. The
+scrobble intuition (count a play once `min(50%, 4:00)` has been
+*heard*, independent of how it ends) is the fix for both.
+
+---
+
+## What we're building
+
+A single classification of every track *exit*, plus one row per exit in
+a listening log, plus the existing denormalized `play_count` /
+`last_played` updated to match the new meaning. Three exit kinds:
+
+| kind | condition |
+|---|---|
+| `complete` | reached natural end, **or** abandoned with `remaining <= tail` |
+| `play` | heard `>= playThreshold`, abandoned before the tail |
+| `skip` | user moved to a *different* track before `playThreshold` |
+
+Not counted, not any kind: decode failure, pause/stop/shutdown before
+the threshold, and tracks shorter than `minTrackLength`.
+
+### The thresholds — named judgements, one file
+
+Follow the `PreviousRestartThreshold` precedent (`backend/queue/queue.go:28`,
+a bare `const` with a comment). A new `backend/queue/listen.go` (or a
+tiny `backend/listencount` package) declares:
+
+```go
+const (
+    // A track this short is deliberated jingle / interstitial and is
+    // never counted, either way.
+    minTrackLength = 30 * time.Second
+    // The scrobble rule: half the track, or four minutes, whichever
+    // comes first (Last.fm / ListenBrainz).
+    playThresholdMax = 4 * time.Minute
+    // "Finished enough": within 15s of the end, or the last 10%,
+    // whichever is larger.  A 10:00 ambient track gets a 60s fade
+    // window; a 2:00 pop song gets 15s.
+    tailWindowFloor    = 15 * time.Second
+    tailWindowFraction = 0.10
+)
+
+func playThreshold(d time.Duration) time.Duration {
+    return min(d/2, playThresholdMax)
+}
+func tailWindow(d time.Duration) time.Duration {
+    return max(d/10, tailWindowFloor)
+}
+```
+
+Classification is a pure function of `(reason, position, duration)` and
+*therefore unit-testable without a player*:
+
+```go
+func classify(reason ExitReason, pos, dur time.Duration) Kind
+```
+
+`ExitReason` is `finished | skipped | failed | abandoned`. `skipped`
+means the queue moved to a different track by user action (Next,
+Previous past the restart threshold, PlayIndex, queue replacement,
+select-from-a-list). `failed` is the decode-error path. `abandoned` is
+pause/stop/unload/shutdown — and in v1 is a no-op (see open question 3).
+
+**"Heard" is approximated by the position at exit.** We read
+`player.CurrentPositionSeconds()` at the moment of the transition, not
+an accumulated listen-time ledger. A user who seeks to 80% and listens
+5 seconds reads as "heard 80%." That is deliberately accepted for v1:
+it is how most players actually behave, it is drastically simpler, and
+the failure mode ("counted a track you skimmed as played") is mild and
+exactly what the scrobble threshold already forgives. Written down
+because "position is not listen time" is the one assumption that will
+look like a bug if it is not.
+
+**Fires once per listen.** Leaving a track already leaves it; the
+`chainID` guard in `player.onPlaybackFinished` (`backend/player/player.go:633`)
+already swallows a stale finish callback, and a transition advances
+`currentIndex` past the finished track. The classifier needs the same
+guard so a Next-then-stale-finish cannot produce two rows. Key it on the
+`(audioFileID, chainID)` the transition was about.
+
+---
+
+## Schema — resolved: fresh design, no migration
+
+The A/B migration agonizing is moot.  This app has two users and both
+are devs, and play counts are explicitly not worth preserving yet — so
+the schema is written as if listening accounting had been designed in
+from the start, and the existing two databases rebuild what they need
+(see below).  There is no migration step and none is re-introduced.
+
+**`play_history` is renamed to `listening_events`** and grows the three
+kinds, plus the raw position/duration the classification was made from:
+
+```sql
+CREATE TABLE IF NOT EXISTS listening_events (
+    id               INTEGER PRIMARY KEY,
+    audio_file_id    INTEGER NOT NULL,
+    kind             TEXT NOT NULL DEFAULT 'complete'
+                     CHECK (kind IN ('complete','play','skip')),
+    position_seconds INTEGER NOT NULL DEFAULT 0,
+    duration_seconds INTEGER NOT NULL DEFAULT 0,
+    occurred_at      DATETIME NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY(audio_file_id) REFERENCES audio_files(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_listening_events_audio_file_id
+    ON listening_events(audio_file_id);
+CREATE INDEX IF NOT EXISTS idx_listening_events_occurred_at
+    ON listening_events(occurred_at);
+```
+
+`position_seconds`/`duration_seconds` are kept raw so a future re-tune
+of the threshold does not force the events to be re-recorded.  `kind`
+stays the write-time classification; the raw reading is evidence, not
+a second copy of the rule.
+
+**The counters are denormalized onto `audio_files`** — `skip_count` /
+`last_skipped` join the existing `play_count` / `last_played`, because
+that is where the hot read path already lives and a log join per track
+row is not acceptable.  This does grow the MIXED-KIND wart (see the
+survey below for the structural answer), but it is the *continuation* of
+the existing design, not a new leak: play counts sat on `audio_files`
+from before this feature existed.
+
+**What happens to the two real databases on next launch.**
+`listening_events` is a new table, created verbatim.  `audio_files`
+gains two columns, which `retireStaleTables` treats as a stale Owned
+table and rebuilds by rescan — dropping `play_count` / `last_played` /
+`tag_status` with it, which is the accepted cost stated in the issue.
+`play_history` is gone from the schema and the datamap, so
+`obsoleteTables` drops it; its (natural-finish-only) timestamp rows go
+with it.  Nothing here is wrong on a fresh install, and on the two dev
+machines the answer is the documented "delete and rescan."
+
+---
+
+## Wiring: where the classifier is called
+
+The risk is not the classifier — it is that **every track-replacement
+path must classify the outgoing track**, and there are many: `Next`,
+`Previous` (past the 3s restart threshold), `PlayIndex`, `playFromStart`,
+`SetQueue` / clear-and-play, remove-current, and select-from-a-list.
+Miss one and that path silently never records a skip.
+
+So the classification is centralized in one queue method —
+
+```go
+// leaveCurrent(reason) classifies the track at currentIndex as it is
+// about to be replaced, and records exactly one listening event.
+// Must be called without q.mu held (it writes to SQLite).
+func (q *Queue) leaveCurrent(reason ExitReason)
+```
+
+— which reads position/duration from the player, calls `classify`, and
+emits the play/skip row + `TrackPlayCountChanged` when `kind != skip`.
+`OnPlaybackFinished(nil)` routes through `leaveCurrent(finished)`, the
+navigation methods route through `leaveCurrent(skipped)` before they
+advance, and `recordPlay` becomes the "did a play happen" half of it.
+
+Because "one path forgot to call it" is the failure mode, a **source
+sweep** pins it, on the pattern of `TestNoDirectRuntimeEmits`
+(`backend/events/noemit_test.go`) and `TestCatalogCoversSchema`: a test
+walks `backend/queue` for assignments to `currentIndex` (and the
+`SetQueue` / remove paths) and fails if a mutation site does not sit
+adjacent to a `leaveCurrent` call. The sweep is the enforcement; the
+central method is the convenience.
+
+`recordPlay` keeps its existing contract *when a play happens* —
+`TrackPlayCountChanged` with `{audioFileId, filePath, playCount,
+lastPlayed}` — so the frontend patch path and
+`playhistory_test.go` keep passing. A skip emits no per-track event in
+v1 (open question 4).
+
+---
+
+## Phases
+
+1. **The classifier.** `listen.go`: the constants, `playThreshold`,
+   `tailWindow`, `classify`. Table-driven unit tests covering every
+   cell of the tristate, the <30s exemption, the tail window on both a
+   10:00 and a 2:00 track, and the clip at the 4:00 cap. No I/O.
+2. **Schema.** *Done in this session.* `listening_events` replaces
+   `play_history`; `skip_count` / `last_skipped` added to
+   `audio_files`; datamap entry and `TestAuthoredCascadesAreDeliberate`
+   allow-list renamed; `recordPlay` writes `listening_events
+   ('complete')`.  `make generate` run; database / datamap / queue
+   tests green.
+3. **Wiring.** `leaveCurrent`, the navigation/finish/error call sites,
+   the `fires once per listen` guard, and the source sweep. Extend
+   `playhistory_test.go` for skip/complete classification through the
+   queue rather than the pure function.
+4. **Smart-playlist field.** `skip_count` (and optionally
+   `days_since_skipped`) in `smartplaylist.go` field/numeric maps and
+   the editor's field list, via subquery. A frontend event for skip —
+   if a UI wants a skip column — follows separately.
+
+## Verification
+
+- **Go:** the classifier is pure and exhaustively unit-tested; the
+  queue wiring is tested in-process with `events.WithSink`
+  (`backend/queue/emit_test.go` is the model), asserting a Next at 90%
+  emits a *play*, a Next at 10% emits a *skip and no play*, a natural
+  finish emits a *complete*.
+- **Database:** schema + datamap tests fail-loud on any new or
+  reclassified table; `database_test.go`'s listening-events round-trip
+  asserts the new table and the four denormalized counter columns.
+- **e2e:** `e2e/specs/play-count.spec.ts` already awaits
+  `TrackPlayCountChanged`; add the skip case (advance early, assert no
+  `TrackPlayCountChanged` and a `skip` row via the `__/test/sql`
+  endpoint if convenient, or via the playlist effect).
+- No visual/component tier needed unless a skip column ships (phase 4).
+
+## Open questions / decisions needed
+
+1. **Migration mechanism.** Resolved — fresh design, no migration (see the schema section).  Play counts are not worth preserving, both users are devs, and `audio_files` / `play_history` rebuild-or-drop on next launch.
+2. **"Position is not listen time."** Accept the approximation for v1,
+   or track accumulated listen seconds (a real ledger on the player) now?
+3. **Abandon on shutdown.** A track paused at 70% and then app-killed:
+   count a `play` (scrobble says heard) or leave it unrecorded? v1
+   proposes *unrecorded* — same as today — to keep the write path off
+   the shutdown critical path.
+4. **Skip event to the frontend.** Emit now (parallel to
+   `TrackPlayCountChanged`) or only when a surface consumes it?

.planning/plans/completed/019-android-touch-model.md

@@ -0,0 +1,408 @@
+# 019 — The Android touch model
+
+**Issue:** #63 (`Area/Library-UI`, `Kind/Feature`, `Priority/High`)
+**Depends on:** #60 (bottom-sheet menus) — closed, merged as PR #176
+**Relates:** #67 (inline links into the menu), #71 ("More" nav), #54
+(native feel), #5/#8 (selection, drag to queue — the desktop semantics
+being diverged from)
+**Status:** shipped (phases 1-4). Its one deliberate remainder is #200.
+
+#73 puts #60 first in Phase 4 because it is "the presentation every
+other item needs", and this is the next one. The Direction on #63 asks
+for the interaction model to be designed as one piece before any of it
+is built, because it *reassigns an existing gesture* rather than adding
+one — `utils/long-press.ts` currently owns the 500ms hold, and every
+context menu in the app is downstream of it.
+
+This document is that design. Everything below is a measurement, or an
+argument for one of the choices #63 leaves open.
+
+---
+
+## The mapping
+
+| gesture | pointer is a finger | pointer is a mouse |
+|---|---|---|
+| single tap / click | **play the row** | select the row |
+| double | — | play the row |
+| long press (500ms) | **enter selection mode** | — |
+| right-click | — | context menu |
+| swipe right | **add to queue** | — |
+| drag | reorder / drag to playlist | reorder / drag to playlist |
+
+Three of those are #63's report unchanged. Two are decisions it left
+open, and one is a deliberate divergence.
+
+---
+
+## Decision 1 — the predicate is the pointer, not the platform
+
+#63 says "the row component needs a platform-aware interaction layer
+rather than shared handlers". It needs an interaction layer; it should
+not be platform-aware.
+
+**The question a row has to answer is not "am I on Android" or "is the
+viewport under 600px" but "what made this event".** `pointerType ===
+'touch'`, read off the event that is being handled, which is already
+how `long-press.ts` decides (`if (e.pointerType !== 'touch') return`)
+and is the only such test in the frontend today.
+
+This is #64's rule — the predicate is named after the capability, not
+the platform — and it carries #64's warning with it. Keyed on a width:
+
+- an Android **tablet** at 600px or more gets click-selects /
+  double-click-plays on a touchscreen, which is the exact inversion
+  this issue exists to fix, on the platform it exists for;
+- a **touchscreen laptop** cannot be described at all, because both
+  pointers are live in the same session on the same row;
+- and a narrow desktop window gets phone semantics with a mouse.
+
+Per event, all three are right for free, and there is no second
+declaration of what a phone does — the thing CLAUDE.md declines to add
+every time it comes up.
+
+**Measured, so this is not an assumption about the WebView.** On the
+reference device (TLP301, Android 14, WebView Chrome 113, 424x439),
+driving a real tap with `adb shell input tap`:
+
+```
+[["down","touch",78,94],["touchstart","touchstart",0,0],["up","touch",78,94]]
+```
+
+`PointerEvent` exists, `pointerType` is `"touch"`, `maxTouchPoints` is
+5, and `(pointer: coarse)` / `(hover: none)` both match.
+
+---
+
+## Decision 2 — there is no double-tap, and the number is why
+
+#63 asks for *single tap → play* **and** *double tap → context menu*.
+Those two cannot both be honoured. The first tap of a double tap is
+indistinguishable from a single tap until the interval expires, so
+"tap plays" necessarily becomes "tap waits to find out whether you
+meant something else, then plays". The app already owns that constant:
+`utils/explore-link.ts` holds a navigation for `DOUBLE_CLICK_GRACE_MS
+= 250` for precisely this reason.
+
+**What it would be added to, measured on the device.** Six runs, from
+the play command to the backend's `TrackChanged`:
+
+```
+155, 123, 85, 56, 91 ms          median ~100
+```
+
+So the app's primary interaction is ~100ms, and a double-tap
+discriminator makes it ~350 — **3.5x, of which 250ms is spent
+deliberately doing nothing** — paid on every track anyone ever plays,
+in order to reach a menu.
+
+It is also against the platform's convention, which counts for more
+than usual here because this is the phone build and nothing else:
+long-press is *how you select* on Android (Gmail, Files, Photos),
+double-tap is zoom or nothing, and a list's menu is either the
+long-press sheet or a per-row overflow.
+
+**So the menu and the selection action bar become the same surface**,
+which is the convention and removes a concept rather than adding one.
+Long-press selects the row it was made on and raises the action bar;
+the bar's actions *are* the context menu's actions, contextualised to
+whatever is selected — one row or forty. #60's bottom sheet stays
+behind it as the overflow, so `contextMenuStyles`, `MenuKeyboard` and
+`menu-surface` are reused rather than reimplemented.
+
+---
+
+## Decision 3 — tap-to-play and selection mode ship together
+
+The obvious phase order is "tap plays first, it is the smallest
+change". It is wrong, and the reason is a capability that exists today
+and is easy to miss.
+
+**A touch user can already multi-select**: tap selects (the desktop
+semantics, which a finger currently gets), and the long-press menu then
+acts on the selection. Move tap to play without shipping selection mode
+in the same change and there is a window — a release, if it lands — in
+which selecting forty tracks to add to a playlist is impossible on a
+phone. That is a regression dressed as an increment.
+
+So phase 1 is both, or neither.
+
+---
+
+## What the code looks like now
+
+| surface | how it binds | selection |
+|---|---|---|
+| `track-list` | delegated on the virtualizer: `click`, `dblclick`, `contextmenu`, `dragstart` | `SelectionController` |
+| `queue-panel` | delegated, same shape | `SelectionController` |
+| `playlist-details` | per row | `SelectionController` |
+| `smart-playlist-details` | per row | `SelectionController` |
+
+All four already share `SelectionController`, and all four resolve a
+row from an event by `data-index` / `data-file-path` on the row. So the
+gesture layer has one shape to talk to, and "selection mode" is a flag
+on the controller they already have rather than a fifth concept.
+
+`utils/long-press.ts` is one document-capture listener that synthesises
+a `contextmenu` — the seam that needed no component to opt in. **This
+plan keeps that shape and changes what the gesture means**, which is
+why it is a rewrite of that file rather than a second listener set: two
+document listeners both claiming the 500ms hold is the fault the file's
+own header warns about.
+
+---
+
+## Two measurements that decide the implementation
+
+**`touch-action` is `auto` on both the virtualizer and the rows.** With
+`auto` the browser owns panning on both axes, so a horizontal drag can
+be claimed as a scroll and our gesture ends in `pointercancel`
+mid-swipe. A row that wants a horizontal swipe has to declare
+`touch-action: pan-y`: the browser keeps the vertical pan (which is the
+virtualizer's scroll, and must stay native or the list stutters) and
+hands us the horizontal axis. This is the single most likely way for
+swipe-to-queue to "work in Chromium and not on the phone".
+
+**The row is 424x52 on the device**, so a swipe threshold in px is a
+fraction of a row height, not of a screen.
+
+**And the third one was found by building phase 1 and then running it**
+— it is not something any browser tier can report. Chrome 113's Android
+WebView **fires its own `contextmenu` on a long press**. `long-press.ts`
+stood down when a trusted one arrived, which was right while both paths
+ended in the same place; once a hold can mean selection mode they end
+in different places, and standing down means the gesture silently does
+the *old* thing. Measured, before the fix:
+
+```
+{"log":["contextmenu isTrusted=true"],
+ "state":{"bar":null,"menuActive":true,"selected":1}}
+```
+
+`yj-long-press` was never announced at all, the context menu opened,
+and all 26 tests in the component tier passed — dispatched pointer
+events do not make a browser synthesise a `contextmenu`.
+
+So the browser's event is a **trigger, not a competitor**: the gesture
+is announced from it, and only a component that claims it suppresses
+the native menu. Unclaimed, it propagates untouched. That is the same
+"browser wins" outcome, reached by asking instead of assuming — and
+verified both ways on the device, a track row entering selection mode
+and an album card still opening its menu.
+
+The tier could not *find* it and can *hold* it: a test cannot dispatch
+a trusted event, but this module has always told its own apart by
+identity rather than `isTrusted`, so an untrusted one from a test takes
+exactly the browser's path.
+
+---
+
+## A tier note: this one can be driven, not only measured
+
+`adb shell input tap|swipe` reaches the WebView as real pointer events,
+which the log above is evidence of. So for the first time the Android
+tier can *perform* the thing under test rather than describe the page
+afterwards — a long press is `input swipe X Y X Y 600`, a swipe right
+is `input swipe X Y X+N Y 120`.
+
+Device CSS pixels from device pixels, on this phone:
+`css = (device - 59) / 2.564` vertically, `css = device / 2.564`
+horizontally (measured from the tap above: 200,300 arrived as 78,94).
+
+This does not make the device a spec tier — it does not run in CI and
+`make ui-test` still has to carry the assertions. It makes "does the
+gesture actually fire on Chrome 113" answerable in seconds.
+
+---
+
+## Phases
+
+**Phase 1 — the seam, tap-to-play, selection mode.** `utils/
+touch-gestures.ts` replacing `long-press.ts`: pointer-typed
+recognition of tap / long-press / horizontal swipe, dispatched as
+composed custom events so a delegated listener in any shadow root
+still works. `SelectionController` gains a mode. `track-list` acts on
+tap and enters the mode on long press. The action bar.
+
+**Phase 2 — swipe right to queue**, with the `touch-action: pan-y`
+finding above and a reveal-and-snap affordance. **Shipped**; what the
+device said about it is the section below.
+
+**Phase 3 — the other three surfaces**, which is mostly wiring, since
+they already share the controller. **Shipped**, and it was not entirely
+wiring — see below.
+
+**Phase 4 — what this leaves behind.** The inline `explore-link`s in a
+row are a single-click target inside a row whose single tap now plays;
+that conflict is #67's, and this plan should not pre-empt its answer
+beyond making tap-to-play win on touch. **Shipped.**
+
+## Phase 3 was not symmetric, in two places
+
+**A tap on a queue row plays that position**, not the list. Copying
+`track-list`'s tap — which sets the queue to the list the row is in —
+would rebuild the queue *from* the queue, discarding its source, its
+shuffle order and everything a user had inserted by hand. It reads as a
+no-op and is not one.
+
+**The queue panel has no swipe, deliberately.** A right swipe means
+*add to the queue* everywhere else it exists, and a queue row is
+already in the queue; the only thing it could mean there is *remove*,
+which is the same gesture with the opposite effect one screen away —
+the fault `utils/icon-language.ts` exists to have fixed for glyphs.
+Removing a queue row is on the row itself (the ×), on its bottom sheet
+since #60, and on the selection bar this phase gave it. The assertion
+is that its rows do **not** carry `data-swipe`, so a swipe there cannot
+silently become a second meaning for the app's one horizontal gesture.
+
+And the affordance became `utils/swipe-to-queue.ts` rather than being
+copied twice. Three lists want it; three copies of "how far is far
+enough" is three chances for them to disagree, which is what
+`utils/library-status.ts` and `utils/ownership.ts` each exist to have
+stopped happening. The shared stylesheet is keyed on `[data-swipe]`
+rather than on a class name, because the three lists call their rows
+two different things and the `touch-action` half of the device fix has
+to reach all of them.
+
+## Phase 4 was already true, which is why it is asserted
+
+A claimed tap has its click swallowed at document capture, so an
+`explore-link` inside the row never sees one and tap-to-play wins with
+no rule of its own. Nothing in the suite would have failed if that
+stopped covering the link, and the symptom — tapping a track's *title*
+navigating to its album instead of playing it — is one a phone user
+meets constantly and a mouse user never does.
+
+**Its test was vacuous when written**, in the way this file keeps
+finding: the tap helper dispatched `pointerdown` and `pointerup` and no
+`click`, so there was nothing to swallow and the assertion held on any
+build. It sends the trailing click now, which also strengthened phase
+1's "a tap plays and does not also select". The fixture needed an MBID
+for the same reason — without one the link asks the backend for a local
+album first and gives up when nothing answers, so "it did not navigate"
+was true of a working build and a broken one alike.
+
+---
+
+## What phase 2 measured, which was not what phase 2 predicted
+
+The `touch-action` finding above is **half** of the answer, and
+shipping only that half would have been the exact failure it warns
+about. Driving a real finger with `adb shell input swipe` across a
+track row, three values, all three on the device:
+
+```
+touch-action: auto    pointerdown, 1 move,  pointercancel
+touch-action: pan-y   pointerdown, 2 moves, pointercancel
+touch-action: none    pointerdown, 2 moves, pointercancel
+```
+
+`touchmove` kept firing in all three. So **Chrome 113's WebView
+cancels the pointer stream ~16px into any drag whatever `touch-action`
+says**, and a swipe recognised from `pointermove` — which is what the
+rest of this module is built on — is a swipe that dies 16px in.
+
+The other half is a **non-passive `touchmove` calling
+`preventDefault()`**: with it, the same swipe ran to 12 moves and a
+`pointerup` at full travel. And both halves are required, which was
+measured rather than assumed — with the `preventDefault` in place and
+`touch-action` back at `auto`, the gesture died after **one** move.
+The reading is that `auto` lets the browser commit to a horizontal pan
+on the first move past slop, before any threshold of ours can have
+been crossed, while `pan-y` leaves it undecided long enough for the
+second move to claim it.
+
+`none` is the one value to avoid: the list stopped scrolling at all.
+With the shipped pair, a vertical drag still scrolls the virtualizer
+81px on the same run that a horizontal one survives.
+
+**`draggable="true"` is not a competitor**, which is the other thing
+the device was asked. No `dragstart` fires from a touch drag on this
+WebView at all, so the drag-to-playlist attribute on every row needs no
+pointer-type gate.
+
+### And it found a phase 1 defect that no tier can see
+
+The native `contextmenu` arrives in **either** order, and phase 1 only
+handled one of them. `nativeSeen` covers the browser's menu arriving
+*during* the hold. The reverse — our 500ms timer firing first, a
+component claiming it, and Chrome delivering its own `contextmenu`
+50–70ms *later* — was suppressed by nothing, so the context menu
+opened on top of the selection bar. Measured over four holds:
+
+```
+hold 1  yj-long-press, then contextmenu isTrusted=true   menu open
+hold 2  yj-long-press                                    clean
+hold 3  yj-long-press, then contextmenu isTrusted=true   menu open
+hold 4  yj-long-press                                    clean
+```
+
+Two in four, on the one surface #63 exists to have changed, and
+invisible to both browser tiers because neither synthesises a
+`contextmenu` from a dispatched press. A press that has produced its
+outcome now suppresses a late one whichever branch it took; six holds
+on the fixed build, six clean.
+
+### The rules phase 2 settled
+
+- **A swipe is not a selection.** It queues the row it was made on,
+  unless that row is one of several *explicitly* selected — the same
+  rule the context menu answers with, because a bar reading "40
+  selected" beside a gesture that quietly queues one of them is two
+  answers to one question. It never changes the selection, which is
+  where it differs from a right-click.
+- **Rightward only.** Nothing is bound to a leftward swipe and
+  claiming one would take a gesture away to do nothing with it.
+- **The commit threshold is a fraction of the row** (0.3, floor 72px),
+  because the row is 424x52 on this device and a bare pixel count is a
+  fraction of a row height on one screen and a third of the width on
+  the next.
+- **The affordance is not only a colour** (WCAG 1.4.1, the rule the
+  playing-row marker exists for): the pane carries the queue icon and
+  words, the words change at the threshold ("Add to queue" → "Release
+  to add" → "Added"), and the outcome is announced in a live region.
+- **The row does not move; its cells do.** `.track-row` is
+  `contain: strict` with `overflow: hidden`, so a pane held at the
+  row's original position while the row translates is a pane at a
+  negative offset inside a clipping box and is simply not painted.
+  Sliding the cells needs no wrapper element in a row that is already
+  a grid.
+- **The travel is written to the row's own style, not rendered.** One
+  render at the start, one at the threshold, one at the end; a
+  virtualizer re-rendering every visible row per frame of one finger's
+  travel is the thing `perf.m1` is about.
+
+## Open questions
+
+1. **Does selection mode have an escape other than the bar's own
+   close?** *Settled: Escape, here; back, not here.*
+
+   Escape leaves the mode, from `selection-bar` rather than from each
+   of the four hosts — that element exists only while the mode does, so
+   it is the one place a dismissal can be attached and detached with
+   the thing it dismisses. It is the same documented exception the
+   overlaid queue's Escape is: **a dismissal, not a shortcut**, so it
+   is not a panel-scoped binding.
+
+   The back gesture is the half that is *not* done, and deliberately.
+   The obvious version — `selection-bar` pushing a history entry — is
+   precisely the fault `navStack` was deleted for: the shell owns the
+   stack (#6/#55) and is the only thing that calls `pushState`, so that
+   two stacks cannot disagree about what one press means. Four lists
+   each reaching for `history` is four stacks. It is also wrong on its
+   own terms, since a mode is per-component and a user who enters one,
+   navigates away and returns has an entry for a mode that no longer
+   exists. #55 settled the shape for a *place*; a mode is not one,
+   which is why it could not simply inherit that answer.
+
+   What it wants is one shell-owned register of dismissible surfaces,
+   which would retro-fit the queue overlay, the dialogs and this alike
+   rather than adding a fourth private answer. **#200.**
+
+2. **Does a tap on a row's favourite icon still toggle it in normal
+   mode?** *Settled in phase 1: yes.* A control inside the row keeps
+   its own tap — the gesture is simply not claimed there, so the click
+   behind it falls through untouched. It is the same rule the shortcut
+   service has for a focused control that owns a key, and it is what
+   keeps the 44px favourite target (#56) from becoming a 44px play
+   target. The queue row's × is the second instance of it.

CONTRIBUTING.md

@@ -0,0 +1,173 @@
+# Contributing to YellowJacket
+
+This is the contributor's half of the [README](README.md): how to build it, how
+to check a change, and how a change gets in. [`CLAUDE.md`](CLAUDE.md) is the
+deep reference — the architecture, and the reasons behind the shape of it —
+and is worth reading before a change of any size, because most of this
+codebase's traps are written down there and nowhere else.
+
+## Building from source
+
+YellowJacket is [Go](https://go.dev/) with a [Lit](https://lit.dev/)/TypeScript
+frontend, bridged by [Wails v3](https://wails.io/).
+
+| Tool | Version |
+|------|---------|
+| Go | 1.25+ |
+| Node.js | 22+ |
+| pnpm | 10+ |
+| Wails CLI | v3 — vendored, no install needed (`go tool wails3`) |
+
+The Wails v3 CLI resolves from the `tool` block in `go.mod`, so there is nothing
+to install globally; `make setup` fetches it with the rest of the tooling.
+
+On Linux, install the system libraries Wails needs. v3 builds against GTK4 +
+WebKitGTK 6.0 by default:
+
+```bash
+sudo apt-get install libasound2-dev libgtk-4-dev libwebkitgtk-6.0-dev   # Debian/Ubuntu
+sudo pacman -S alsa-lib gtk4 webkitgtk-6.0                              # Arch
+```
+
+A machine without `webkitgtk-6.0` can still build with `-tags gtk3` against the
+older WebKit2GTK 4.1 stack, but that is an escape hatch, not what CI or a
+release builds. macOS and Windows need no extra system packages. Run
+`go tool wails3 doctor` to check your environment.
+
+```bash
+make setup        # install tooling, frontend packages and the git hooks
+make dev          # run with hot-reload
+make build-dev    # debug build with symbols
+make build-prod   # production build (stripped and trimmed)
+make android      # the arm64 APK, into bin/
+```
+
+The `Makefile` is the front door and carries a one-line description against
+each target; `Taskfile.yml` and `build/<platform>/Taskfile.yml` are the build
+implementation behind it and are not called directly.
+
+## Generated code
+
+Two generators run from `go generate ./...`, which `make generate` wraps:
+**sqlc** turns `backend/database/sql/queries/` into Go in
+`backend/database/sql/sqlcgen/`, and **templ** turns `.templ` files into
+`*_templ.go` beside them. Never edit either output by hand — run
+`make generate` after touching a `.sql` or a `.templ` file.
+
+The TypeScript bindings in `frontend/bindings/` are generated by `wails3`
+rather than by `go generate`, so they are a separate step: `make bindings`
+regenerates them and `make bindings-check` fails if they are stale.
+`frontend/src/events.ts` is generated too, from `backend/events/events.go`.
+
+A pre-commit hook checks that all of this is fresh, so the usual way to meet it
+is a failing commit rather than a bug.
+
+## Checking a change
+
+Run the tier the change actually demands, not the cheapest one.
+
+| Change | Command |
+|---|---|
+| Go | `make lint` and `make test` — both cover all three build configurations |
+| A frontend component or store | `make ui-test` (Vitest in a real Chromium, no backend) |
+| A user-visible flow | `make e2e`, against a running `make dev-headless` |
+| CSS | `make css-check` — see the Chrome 113 note below |
+| Anything cosmetic | look at a screenshot; several bugs here were invisible to every assertion and obvious in an image |
+
+`make test` needs the fixture library, which is generated rather than
+committed — it runs `make testdata` itself (about a second).
+
+The end-to-end tier drives the real app with no display at all: `make
+dev-headless` starts it in the background on `:34115` (add `SEED=<name>` for a
+seeded library, built by `make sandbox-seed NAME=<name>`), `make dev-logs` tails
+it and `make dev-stop` stops it. **Check the port before starting one** — if
+`:34115` is already answering, someone else's app is there, and a green result
+about their build is worse than no result.
+
+Two smaller checks exist because the failure they catch is silent:
+`make bindings-check` (stale generated bindings) and `make css-check`, which is
+two passes — one fails on a `css` literal ended early by a backtick inside a
+comment, the other on a nested CSS rule that begins with a bare element
+selector. Chrome 113 is what the reference Android device renders with, and it
+drops such a rule without a word.
+
+`make vulncheck` runs govulncheck over the module.
+
+## The issue tracker is the source of truth
+
+Work is described by issues before it is described by branches, and the tracker
+is shared with people who cannot see your terminal.
+
+- **Search before starting**, closed issues included: `./scripts/issue.sh search
+  <terms>`. "That was fixed three weeks ago" is the cheapest possible answer.
+- **Claim before the first edit**, not before the commit:
+  `./scripts/issue.sh claim <n>` sets the assignee, applies `Status/In Progress`
+  and comments with the branch, so the work is visibly taken *while it is being
+  done*. It refuses if somebody else holds it — talk to them rather than working
+  around it.
+- **If no issue covers the work, open one first** (`./scripts/issue.sh new`).
+- **Findings get filed.** A bug tripped over on the way to something else is an
+  issue with a reproduction, not a wider diff and not a sentence in a chat log.
+- **#73 is the roadmap** and states the order the backlog should be worked in.
+
+`scripts/issue.sh` is the whole interface (`list`, `mine`, `search`, `show`,
+`new`, `claim`, `unclaim`, `comment`, `close`, `label`, `depends`, `labels`) and
+wants a `GITEA_TOKEN` with `write:issue`. The labels are a taxonomy rather than
+tags: `Kind/*`, `Area/*`, `Priority/*`, `Platform/*`, plus `Reviewed/*` and
+`Status/*`, of which the last two are exclusive scopes.
+
+## Commits and pull requests
+
+`main` is protected, so a branch and a PR are the only way in. Branch from
+`origin/main`, and name the branch after the issue (`fix/140-…`, `feat/25-…`).
+
+Commit subjects are [Conventional Commits](https://www.conventionalcommits.org/)
+— `type(scope): subject`, imperative, ≤72 characters — and are enforced by a
+`commit-msg` hook and by CI (`make commit-check`). This is load-bearing rather
+than decorative: semantic-release reads the **type** to decide the next version,
+so a CI-only change is `ci:` and never `fix(ci):`, which would ship a patch
+release. `make release-dry` prints what a release would cut right now.
+
+**The closing keyword goes in the commit body**, one issue per line, because
+Gitea parses commit messages that reach `main` and does not parse the PR body:
+
+```
+docs: rewrite the README as a landing page
+
+<why>
+
+Closes #50
+```
+
+A PR body carries a commit-to-issue table, the verification you actually ran
+(with results), and a `Closes` list for whoever reads it.
+
+## Style
+
+- **Go** — golangci-lint v2, strict: `err113` (static errors), `nlreturn`,
+  `wsl_v5`, `godot`, `sloglint`, `perfsprint`, and imports grouped stdlib →
+  third-party → `yellowjacket/…` by gci.
+- **TypeScript** — strict mode, no implicit `any`, no unused locals or
+  parameters.
+- Match the surrounding code. Where `CLAUDE.md` explains why something is shaped
+  the way it is, that shape is load-bearing and there is usually a test pinning
+  it.
+
+Hooks do most of the enforcing (`lefthook.yml`, installed by `make setup`):
+pre-commit runs vet, lint, the codegen checks, the frontend typecheck and the
+two CSS checks in parallel; pre-push runs the Go suite and the UI tier,
+deliberately one after the other rather than together.
+
+## Where the rest of the documentation is
+
+- [`CLAUDE.md`](CLAUDE.md) — architecture and constraints, in depth.
+- [`docs/PROFILING.md`](docs/PROFILING.md) — Go pprof and frontend profiling.
+- [`docs/android-release.md`](docs/android-release.md) — the APK, its signing
+  key, and what the release workflow checks.
+- [`docs/index-cache.md`](docs/index-cache.md) — the search-index build cache
+  and why it has a snapshot.
+- [`packaging/arch/README.md`](packaging/arch/README.md),
+  [`packaging/homebrew/README.md`](packaging/homebrew/README.md) — the two
+  package channels.
+- `.planning/` — design documents and measured history, not a queue. The queue
+  is the tracker.

Makefile

@@ -160,8 +160,11 @@ ui-watch: ## Same suite, in watch mode
 ui-visual: ## Run the suite including screenshot comparisons
 	@cd frontend && YJ_VISUAL=1 npx vitest run $(UI_ARGS)
 
-ui-visual-update: ## Re-record the screenshot baselines
-	@cd frontend && YJ_VISUAL=1 npx vitest run --update $(UI_ARGS)
+# `--update=true`, never a bare `--update`: vitest takes the following
+# positional as the flag's value, so `--update <path>` swallows the path
+# and re-records every baseline in the repo instead of the one named.
+ui-visual-update: ## Re-record the screenshot baselines (UI_ARGS=<path> to filter)
+	@cd frontend && YJ_VISUAL=1 npx vitest run --update=true $(UI_ARGS)
 
 ui-setup: ## Install the Vitest browser provider's own Chromium (once)
 	@cd frontend && pnpm install && npx playwright install chromium
@@ -172,19 +175,24 @@ ui-setup: ## Install the Vitest browser provider's own Chromium (once)
 bindings-check: ## Fail if the generated bindings are stale
 	@./scripts/bindings-check.sh
 
+# Two CSS traps that report a long way from their cause, or not at all.
 # A backtick inside a comment in a css`` literal ends the literal, and
 # what you get back is a type error about CSSResult, or every test in
-# the suite failing to import. Four sessions, three plans. Instant.
+# the suite failing to import. Four sessions, three plans. And a nested
+# rule starting with an element name is dropped by the device's
+# Chrome 113 in silence -- no tier here runs an engine that can see it.
+# Instant.
 .PHONY: css-check
-css-check: ## Fail if a css`` literal was ended early by a backtick in a comment
+css-check: ## Fail on a css`` literal ended early by a backtick, or a nested rule needing an &
 	@cd frontend && node scripts/check-css-literals.mjs
+	@cd frontend && node scripts/check-css-nesting.mjs
 
 # .pi/ and CLAUDE.md document commands, and a doc that documents a
 # command wrongly is worse than no doc: an agent runs it confidently.
 # Every command in them is a make target on purpose, so this is
 # checkable.  It also asserts AGENTS.md is a symlink to CLAUDE.md, so the
 # two harnesses cannot drift onto two descriptions of one project.
-skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md is not a symlink
+skill-check: ## Fail if the docs name a missing make target, or AGENTS.md is not a symlink
 	@./scripts/skill-check.sh
 
 # Conventional Commits, which CLAUDE.md claimed CI enforced for a long

README.md

@@ -2,112 +2,139 @@
 
 *Music how it was meant to bee.*
 
-YellowJacket is a fast, cross-platform desktop music player for your local
-collection. It plays your files, keeps your library tidy, and helps you discover
-and organize your music — all in a clean, responsive interface. No accounts, no
-streaming, no telemetry: just your music on your machine.
+YellowJacket plays the music you already own. Point it at your folders and it
+scans them, reads the tags and the cover art, and gives you a library you can
+browse, search, queue and tidy up — on your own machine, with no account, no
+streaming service and no telemetry.
 
-Runs on **Linux**, **macOS**, and **Windows**.
+It plays **MP3**, **FLAC**, **OGG Vorbis** and **WAV**, on **Linux** and
+**Android**, and builds from source on **macOS**.
 
-## Features
+![The track list, with something playing](docs/images/library.png)
 
-### Play your music
-- Plays **MP3, FLAC, OGG Vorbis, and WAV**
-- Play, pause, seek, and volume control with a mute toggle
-- Gapless, glitch-free seeking backed by a read-ahead buffer
-- A queue you can add to, reorder, and shuffle, with play-next support
-- Shuffle and repeat (off / all / one)
-- Picks up right where you left off — remembers your track, position, and volume between sessions
-- Media-key and MPRIS support on Linux, so your desktop's playback controls just work
+## What it does
 
-### Keep your library organized
-- Point it at your music folders and it scans them automatically
-- Reads tags and embedded cover art, and de-duplicates artwork so it isn't stored twice
-- Incremental sync — only new or changed files get reprocessed, and deleted files are cleaned up
-- Browse by **album**, **artist**, or **genre**, or search across everything
-- Mark favorites and see what you've been listening to with play history
-- Edit track tags directly when something's off
+**Plays your files.** Play, pause, seek and volume with a mute toggle; a
+read-ahead buffer so seeking is instant rather than gappy; a queue you can add
+to, reorder and shuffle, with play-next; shuffle and repeat (off / all / one).
+It remembers the track, the position and the queue between sessions, and it
+answers your desktop's media keys — MPRIS on Linux, a media notification and
+lock-screen controls on Android.
 
-### Playlists
-- Create playlists, drag tracks in, and reorder them
-- **Smart playlists** that build themselves from rules (by genre, rating, play count, and more)
-- Pin a default playlist and spot duplicate tracks at a glance
+**Keeps the library tidy.** It scans the folders you give it and rescans only
+what changed, so a big library costs its full scan once. It de-duplicates
+embedded cover art rather than storing the same image a hundred times, notices
+files that have gone away, and spots duplicate tracks. Browse by album, artist
+or genre, search across everything, mark favourites, and see what you have been
+playing.
 
-### Discover and clean up (powered by MusicBrainz)
-- **Explore** — browse artists, releases, and genres from the MusicBrainz catalog, not just what's already in your library
-- **Auto-tag** — match your files against MusicBrainz to fill in correct artist, album, and track metadata, with a review step before anything is written
-- **Lyrics search** — find a track by a line you remember
+**Playlists, and playlists that write themselves.** Drag tracks in and reorder
+them, or describe what you want — genre, play count, how long since you played
+it — and let a smart playlist keep itself up to date.
+
+**Explore and auto-tag, from the MusicBrainz catalog.** Explore browses artists,
+releases and genres from the catalog rather than only from what you own, so an
+album page can tell you that you have nine of its twelve tracks. Auto-tag
+matches your files against MusicBrainz and fills in the metadata that is
+missing, with a review step before anything is written to disk. Lyrics search
+finds a track from a line you remember.
+
+Explore needs its catalog, which is a one-off ~0.6 GB download from
+**Settings → Search Index**. It asks first on a metered connection, and
+everything else in the app works without it.
 
 ## Install
 
-Download the latest build for your platform from the
+Every download comes from the
 [releases page](https://git.ljones.me/yonlu/yellowjacket/releases).
 
-| Platform | Download |
-|----------|----------|
-| Linux | `yellowjacket-linux-amd64` |
-| macOS | `yellowjacket-darwin-universal.app.zip` (Apple Silicon + Intel) |
-| Windows | `yellowjacket-windows-amd64.exe` |
+### Linux
 
-Prefer to build it yourself? See [Building from source](#building-from-source).
+Download `yellowjacket-<version>-linux-amd64.tar.gz` from the latest release and
+unpack it. It holds the binary, a `.desktop` entry and an icon.
 
-## Getting started
+On **Arch**, install it from the package registry instead and get updates with
+the rest of your system — the one-time key import and `pacman.conf` block are in
+[`packaging/arch/README.md`](packaging/arch/README.md):
+
+```bash
+sudo pacman -Sy yellowjacket
+```
+
+### Android
+
+Install the APK from the release page, or from the URL below, which always
+points at the newest build:
+
+```
+https://git.ljones.me/api/packages/yonlu/generic/yellowjacket-android/latest/yellowjacket.apk
+```
+
+That URL needs no credentials, so [Obtainium](https://obtainium.imranr.dev/) can
+poll it directly and keep the app up to date. The build is `arm64-v8a` only, and
+[`docs/android-release.md`](docs/android-release.md) says why.
+
+### macOS
+
+Homebrew builds it from source on your own Mac — there is no prebuilt `.app`,
+because a signed macOS bundle needs a macOS machine to produce it and the
+release runner is a Linux container.
+
+```bash
+brew install shadow-puppet/yellowjacket/yellowjacket
+```
+
+See [`packaging/homebrew/README.md`](packaging/homebrew/README.md).
+
+### Windows
+
+Not published. It cross-compiles cleanly, but no Windows build of this app has
+ever been *run*, and nothing here can exercise one — so shipping it would be a
+promise that cannot be kept. You can still build it yourself: see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### Coming from a 1.x install?
+
+Versions restarted at **0.0.1** when releases became automatic, which every
+package manager reads as a downgrade. It costs one reinstall, once — the details
+are with each channel: [Homebrew](packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once),
+[Android](docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x).
+
+## First run
 
 1. Launch YellowJacket.
-2. Open **Settings** and add the folder(s) where your music lives.
-3. Let the initial scan finish — you'll see progress as it works.
-4. Browse by album, artist, or genre, queue something up, and press play.
+2. Add the folder your music lives in — the first-run wizard asks, and
+   **Settings → Libraries** is where you add more later.
+3. Watch the scan finish. It reports progress, and you can browse while it runs.
+4. Queue something and press play.
 
-Your library and settings are stored locally:
+Your library and settings stay on your machine:
 
 | | Linux / macOS | Windows |
 |---|---|---|
 | Config | `~/.config/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\config` |
 | Library data | `~/.local/share/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\data` |
 
-## Building from source
+Setting `YJ_HOME` moves both, which is how you keep a second library separate.
 
-YellowJacket is built with [Go](https://go.dev/) and a
-[Lit](https://lit.dev/)/TypeScript frontend, bridged by the
-[Wails](https://wails.io/) framework.
+## More screenshots
 
-**Prerequisites**
+An album page knows what you own, and says so:
 
-| Tool | Version |
-|------|---------|
-| Go | 1.25+ |
-| Node.js | 22+ |
-| pnpm | 10+ |
-| Wails CLI | v3 — vendored, no install needed (`go tool wails3`) |
+![An album page, with two discs and the transport playing](docs/images/album.png)
 
-The Wails v3 CLI resolves from the `tool` block in `go.mod`, so there is nothing
-to install globally; `make setup` fetches it with the rest of the tooling.
+The home page suggests somewhere to start rather than opening on a wall of
+everything:
 
-On Linux, install the system libraries Wails needs. v3 builds against GTK4 +
-WebKitGTK 6.0 by default:
+![The home page's shelves](docs/images/home.png)
 
-```bash
-sudo apt-get install libasound2-dev libgtk-4-dev libwebkitgtk-6.0-dev   # Debian/Ubuntu
-sudo pacman -S alsa-lib gtk4 webkitgtk-6.0                              # Arch
-```
+## Contributing, and the rest of the documentation
 
-A machine without `webkitgtk-6.0` can still build with `-tags gtk3` against the
-older WebKit2GTK 4.1 stack, but that is an escape hatch, not what CI or a
-release builds.
-
-macOS and Windows need no extra system packages. Run `go tool wails3 doctor` to
-check your environment.
-
-**Build**
-
-```bash
-make setup        # install tooling and git hooks
-make dev          # run with hot-reload
-make build-prod   # produce a release binary
-```
-
-More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
-architecture, the conventions and the reasons behind them. What is
-being worked on is [the issue
-tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
-roadmap.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — build it from source, run the tests,
+  and how a change gets in.
+- [`CLAUDE.md`](CLAUDE.md) — the deep reference: the architecture and the reasons
+  behind the shape of it.
+- [The issue tracker](https://git.ljones.me/yonlu/yellowjacket/issues) is what
+  is wanted and what is being worked on; **#73** is the roadmap.
+- [Releases](https://git.ljones.me/yonlu/yellowjacket/releases) double as the
+  changelog — every one is generated from the commits it contains.

backend/androidlog/android.go

@@ -0,0 +1,55 @@
+//go:build android
+
+// The write itself, and nothing else. Everything decidable off a phone
+// is in androidlog.go; see the package comment for why.
+
+package androidlog
+
+/*
+#cgo LDFLAGS: -llog
+#include <stdlib.h>
+#include <android/log.h>
+*/
+import "C"
+
+import (
+	"log/slog"
+	"unsafe"
+)
+
+// The priorities in androidlog.go are android/log.h's own values, and
+// these are what says so. A constant expression that would be negative
+// does not compile as a uint, so a renumbered header fails the build
+// here rather than logging everything at the wrong severity -- which is
+// the failure that would otherwise be invisible, since logcat would
+// happily print whatever number it was handed.
+const (
+	_ = uint(C.ANDROID_LOG_VERBOSE - PrioVerbose)
+	_ = uint(PrioVerbose - C.ANDROID_LOG_VERBOSE)
+	_ = uint(C.ANDROID_LOG_DEBUG - PrioDebug)
+	_ = uint(PrioDebug - C.ANDROID_LOG_DEBUG)
+	_ = uint(C.ANDROID_LOG_INFO - PrioInfo)
+	_ = uint(PrioInfo - C.ANDROID_LOG_INFO)
+	_ = uint(C.ANDROID_LOG_WARN - PrioWarn)
+	_ = uint(PrioWarn - C.ANDROID_LOG_WARN)
+	_ = uint(C.ANDROID_LOG_ERROR - PrioError)
+	_ = uint(PrioError - C.ANDROID_LOG_ERROR)
+	_ = uint(C.ANDROID_LOG_FATAL - PrioFatal)
+	_ = uint(PrioFatal - C.ANDROID_LOG_FATAL)
+)
+
+// New returns the handler main() installs on Android.
+func New(opts *slog.HandlerOptions) slog.Handler {
+	return NewHandler(opts, write)
+}
+
+// write hands one line to liblog.
+func write(prio int, tag, msg string) {
+	cTag := C.CString(tag)
+	defer C.free(unsafe.Pointer(cTag))
+
+	cMsg := C.CString(msg)
+	defer C.free(unsafe.Pointer(cMsg))
+
+	C.__android_log_write(C.int(prio), cTag, cMsg)
+}

backend/androidlog/androidlog.go

@@ -0,0 +1,250 @@
+// Package androidlog routes slog to logcat.
+//
+// **An Android app's fd 1 and 2 go to /dev/null**, so every line this
+// app writes with slog is discarded on that platform -- including the
+// one naming the error it is about to os.Exit on. #52 is what that
+// cost: a process that vanished with no tombstone, no AndroidRuntime
+// stack and nothing in `logcat -b crash`, at Priority/Critical for
+// months, whose entire diagnosis was one slog.Error main.go was
+// already writing.
+//
+// The platform's own sink is __android_log_write, which is a handful
+// of cgo -- and cgo compiled by nothing `make lint` or `make test`
+// runs, since the only toolchain that builds the android tag is a
+// cross-compiler and the only thing that runs it is a phone. So the
+// split here is the one backend/mediacontrols/androidpayload.go makes,
+// pushed as far as it will go: **everything except the write itself is
+// in this file, untagged**. The priority mapping, the formatting, the
+// chunking and the handler's own attr and group bookkeeping are
+// ordinary Go that `go test` exercises on any platform; android.go is
+// fifteen lines that hand a string to liblog.
+package androidlog
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"strconv"
+	"strings"
+	"sync"
+)
+
+// Tag is what logcat labels these lines with.
+//
+// It is a constant of ours rather than the application id, because the
+// debug build carries `applicationIdSuffix ".dev"` so that it can be
+// installed beside the release app -- so a tag derived from the package
+// name is a *different* tag on the one build that can be inspected, and
+// the filter that is supposed to show these lines would hide them on
+// exactly the build used to look for them.
+const Tag = "yellowjacket"
+
+// Android's priorities, from android/log.h. These are the values
+// __android_log_write takes; android.go asserts at compile time that
+// they still match the header, so a renumbered platform is a build
+// failure here rather than a warning silently logged as an error.
+const (
+	PrioVerbose = 2
+	PrioDebug   = 3
+	PrioInfo    = 4
+	PrioWarn    = 5
+	PrioError   = 6
+	PrioFatal   = 7
+)
+
+// maxPayload is how much of one line liblog will carry.
+//
+// The kernel logger's entry is 4068 bytes for the tag, the message and
+// their two NULs together, and what does not fit is **dropped without
+// comment** -- so a long line would be truncated in the middle of the
+// thing worth reading. 3500 leaves room for the tag and for the "(N/M)"
+// a continuation carries.
+const maxPayload = 3500
+
+// WriteFunc is the platform sink: one already-formatted line, at one
+// priority, under one tag.
+//
+// It is a parameter rather than a package-level function so that the
+// handler can be driven by a test on a machine with no liblog at all.
+type WriteFunc func(prio int, tag, msg string)
+
+// Priority maps a slog level onto an Android one.
+//
+// slog's levels are open -- a caller may define its own at any int --
+// so this is a banding rather than a lookup: anything below Info is
+// debug, anything at or above Error is error. A custom level between
+// two of the standard ones lands in the band beneath it, which is what
+// slog's own level naming does.
+func Priority(level slog.Level) int {
+	switch {
+	case level < slog.LevelDebug:
+		return PrioVerbose
+	case level < slog.LevelInfo:
+		return PrioDebug
+	case level < slog.LevelWarn:
+		return PrioInfo
+	case level < slog.LevelError:
+		return PrioWarn
+	default:
+		return PrioError
+	}
+}
+
+// Handler formats records with slog's own TextHandler and hands each
+// line to a WriteFunc.
+//
+// It delegates the formatting rather than doing it, because WithAttrs
+// and WithGroup are the half of slog.Handler that is easy to get subtly
+// wrong -- and a logger whose groups are wrong is a logger nobody reads.
+// What it does own is what logcat needs and TextHandler does not know
+// about: the priority, and the fact that a line has a maximum length.
+type Handler struct {
+	write WriteFunc
+
+	// mu guards buf, which the delegate writes into. slog.Handler is
+	// documented as safe for concurrent use.
+	mu       *sync.Mutex
+	buf      *bytes.Buffer
+	delegate slog.Handler
+}
+
+// NewHandler builds a handler over an arbitrary sink.
+//
+// The time and the level are dropped from the formatted line: logcat
+// stamps every entry with both, and repeating them costs a quarter of
+// the width of a phone-sized terminal to say the same thing twice.
+func NewHandler(opts *slog.HandlerOptions, write WriteFunc) *Handler {
+	buf := &bytes.Buffer{}
+
+	inner := &slog.HandlerOptions{}
+	if opts != nil {
+		*inner = *opts
+	}
+
+	user := inner.ReplaceAttr
+	inner.ReplaceAttr = func(groups []string, a slog.Attr) slog.Attr {
+		if len(groups) == 0 && isBuiltin(a) {
+			return slog.Attr{}
+		}
+
+		if user != nil {
+			return user(groups, a)
+		}
+
+		return a
+	}
+
+	return &Handler{
+		write:    write,
+		mu:       &sync.Mutex{},
+		buf:      buf,
+		delegate: slog.NewTextHandler(buf, inner),
+	}
+}
+
+// isBuiltin reports whether an attr is slog's own time or level,
+// rather than a caller's attribute that happens to share the name.
+//
+// ReplaceAttr cannot tell those apart by key. It is called with an
+// empty group path for the built-ins *and* for every top-level
+// attribute, so a key comparison alone silently eats a caller's own
+// "level" or "time" -- which is not hypothetical: the probe that
+// verified this package on the device logged one, and the attribute
+// vanished. The kinds are what separate them, because slog builds the
+// built-ins as slog.Any(LevelKey, r.Level) and slog.Time(TimeKey, ...)
+// and an attribute value of type slog.Level is not something a caller
+// passes by accident.
+func isBuiltin(a slog.Attr) bool {
+	switch a.Key {
+	case slog.TimeKey:
+		return a.Value.Kind() == slog.KindTime
+	case slog.LevelKey:
+		_, ok := a.Value.Any().(slog.Level)
+
+		return ok
+	default:
+		return false
+	}
+}
+
+// Enabled reports whether the level is worth formatting.
+func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool {
+	return h.delegate.Enabled(ctx, level)
+}
+
+// Handle formats one record and writes it out, in as many entries as
+// its length demands.
+func (h *Handler) Handle(ctx context.Context, rec slog.Record) error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	h.buf.Reset()
+
+	if err := h.delegate.Handle(ctx, rec); err != nil {
+		return err
+	}
+
+	prio := Priority(rec.Level)
+	for _, line := range Chunk(strings.TrimRight(h.buf.String(), "\n")) {
+		h.write(prio, Tag, line)
+	}
+
+	return nil
+}
+
+// WithAttrs returns a handler carrying the given attributes.
+func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return h.derive(h.delegate.WithAttrs(attrs))
+}
+
+// WithGroup returns a handler that qualifies subsequent attributes.
+func (h *Handler) WithGroup(name string) slog.Handler {
+	return h.derive(h.delegate.WithGroup(name))
+}
+
+// derive shares the buffer and its mutex with the parent.
+//
+// They must be shared rather than copied: the delegate returned by
+// WithAttrs writes into the *same* buffer this one does, so a second
+// mutex would guard nothing and two loggers derived from one would
+// interleave their bytes into a single line.
+func (h *Handler) derive(delegate slog.Handler) *Handler {
+	return &Handler{
+		write:    h.write,
+		mu:       h.mu,
+		buf:      h.buf,
+		delegate: delegate,
+	}
+}
+
+// Chunk splits a formatted record into entries liblog will carry
+// whole.
+//
+// A record short enough to fit is returned as it is, which is nearly
+// every record; the numbering only appears where something was going
+// to be silently truncated anyway. It splits on bytes rather than runes
+// because the limit is a byte count -- a multi-byte rune straddling the
+// boundary is a mojibake character in a log line, against a lost one.
+func Chunk(msg string) []string {
+	if len(msg) <= maxPayload {
+		return []string{msg}
+	}
+
+	var parts []string
+
+	for rest := msg; rest != ""; {
+		n := min(maxPayload, len(rest))
+		parts = append(parts, rest[:n])
+		rest = rest[n:]
+	}
+
+	numbered := make([]string, 0, len(parts))
+	for i, p := range parts {
+		numbered = append(
+			numbered,
+			"("+strconv.Itoa(i+1)+"/"+strconv.Itoa(len(parts))+") "+p,
+		)
+	}
+
+	return numbered
+}

backend/androidlog/androidlog_test.go

@@ -0,0 +1,355 @@
+package androidlog_test
+
+import (
+	"log/slog"
+	"strings"
+	"sync"
+	"testing"
+
+	"yellowjacket/backend/androidlog"
+)
+
+// entry is one call to the sink.
+type entry struct {
+	prio int
+	tag  string
+	msg  string
+}
+
+// recorder is the platform write, on a machine with no platform.
+type recorder struct {
+	mu      sync.Mutex
+	entries []entry
+}
+
+func (r *recorder) write(prio int, tag, msg string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.entries = append(r.entries, entry{prio: prio, tag: tag, msg: msg})
+}
+
+func (r *recorder) only(t *testing.T) entry {
+	t.Helper()
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if len(r.entries) != 1 {
+		t.Fatalf("want exactly one entry, got %d: %v", len(r.entries), r.entries)
+	}
+
+	return r.entries[0]
+}
+
+func newLogger(r *recorder, level slog.Level) *slog.Logger {
+	return slog.New(androidlog.NewHandler(
+		&slog.HandlerOptions{Level: level},
+		r.write,
+	))
+}
+
+// TestPriorityMapsEveryLevel pins the level banding.
+//
+// This is the one thing in #160 that a wrong answer hides rather than
+// breaks: logcat prints whatever priority it is handed, so an Error
+// filed as Info is a line that is present, correct and invisible to
+// every filter anyone would use to look for it.
+func TestPriorityMapsEveryLevel(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		level slog.Level
+		want  int
+	}{
+		{"below debug is verbose", slog.LevelDebug - 1, androidlog.PrioVerbose},
+		{"debug", slog.LevelDebug, androidlog.PrioDebug},
+		{"info", slog.LevelInfo, androidlog.PrioInfo},
+		{"warn", slog.LevelWarn, androidlog.PrioWarn},
+		{"error", slog.LevelError, androidlog.PrioError},
+
+		// slog's levels are open, so a caller may sit between two of
+		// the named ones.  Each lands in the band beneath it, which is
+		// what slog's own level naming does ("INFO+2").
+		{"between info and warn", slog.LevelInfo + 2, androidlog.PrioInfo},
+		{"between warn and error", slog.LevelWarn + 1, androidlog.PrioWarn},
+		{"above error", slog.LevelError + 4, androidlog.PrioError},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := androidlog.Priority(tt.level); got != tt.want {
+				t.Errorf("Priority(%v) = %d, want %d", tt.level, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestPrioritiesAreTheHeadersValues pins the constants themselves.
+//
+// android.go asserts these against android/log.h at compile time, but
+// only a cross-compiler ever builds that file.  This is the assertion
+// that runs in CI, and the numbers are written out longhand on purpose
+// -- comparing a constant to itself would pass on any renumbering.
+func TestPrioritiesAreTheHeadersValues(t *testing.T) {
+	t.Parallel()
+
+	for _, tt := range []struct {
+		name string
+		got  int
+		want int
+	}{
+		{"verbose", androidlog.PrioVerbose, 2},
+		{"debug", androidlog.PrioDebug, 3},
+		{"info", androidlog.PrioInfo, 4},
+		{"warn", androidlog.PrioWarn, 5},
+		{"error", androidlog.PrioError, 6},
+		{"fatal", androidlog.PrioFatal, 7},
+	} {
+		if tt.got != tt.want {
+			t.Errorf("%s priority = %d, want %d", tt.name, tt.got, tt.want)
+		}
+	}
+}
+
+// TestRecordReachesTheSink is the whole point of the package: a line
+// written with slog arrives, under the app's tag, at the right
+// priority.
+func TestRecordReachesTheSink(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	newLogger(rec, slog.LevelInfo).Error("application error", "err", "boom")
+
+	got := rec.only(t)
+
+	if got.prio != androidlog.PrioError {
+		t.Errorf("priority = %d, want %d", got.prio, androidlog.PrioError)
+	}
+
+	if got.tag != androidlog.Tag {
+		t.Errorf("tag = %q, want %q", got.tag, androidlog.Tag)
+	}
+
+	if !strings.Contains(got.msg, "application error") {
+		t.Errorf("message %q does not carry the message", got.msg)
+	}
+
+	if !strings.Contains(got.msg, `err=boom`) {
+		t.Errorf("message %q does not carry the attribute", got.msg)
+	}
+}
+
+// TestTheTagIsNotTheApplicationID guards the trap the tag exists to
+// avoid.
+//
+// The debug build carries `applicationIdSuffix ".dev"`, so it is
+// installed as app.yellowjacket.dev -- and it is the *only* build whose
+// WebView can be inspected, so it is the build anyone debugging this
+// app is running.  A tag derived from the application id therefore
+// differs between the build being looked at and the build the filter
+// was written for, which is the failure this whole issue is about
+// wearing a different hat.
+func TestTheTagIsNotTheApplicationID(t *testing.T) {
+	t.Parallel()
+
+	if strings.Contains(androidlog.Tag, ".") {
+		t.Errorf(
+			"tag %q looks like an application id; it must be stable "+
+				"across the debug suffix",
+			androidlog.Tag,
+		)
+	}
+
+	// Logcat's tag field is 23 bytes.  A longer one is truncated, and a
+	// truncated tag matches no filter.
+	if len(androidlog.Tag) > 23 {
+		t.Errorf("tag %q is %d bytes, over logcat's 23", androidlog.Tag, len(androidlog.Tag))
+	}
+}
+
+// TestTimeAndLevelAreDropped checks the formatting decision.
+//
+// logcat stamps every entry with a timestamp and a priority letter, so
+// carrying slog's own is the same information twice on a 424px screen.
+func TestTimeAndLevelAreDropped(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	newLogger(rec, slog.LevelInfo).Warn("scan finished", "files", 1577)
+
+	got := rec.only(t).msg
+
+	if strings.Contains(got, "time=") {
+		t.Errorf("message %q still carries a timestamp", got)
+	}
+
+	if strings.Contains(got, "level=") {
+		t.Errorf("message %q still carries a level", got)
+	}
+
+	if !strings.Contains(got, "files=1577") {
+		t.Errorf("message %q lost its attributes with them", got)
+	}
+}
+
+// TestACallersOwnLevelAttrSurvives is a regression, and it was found on
+// the phone rather than here.
+//
+// Dropping slog's built-in time and level by key alone also drops a
+// caller's attribute of the same name, because ReplaceAttr sees an
+// empty group path for both. The probe that verified this package on
+// the device wrote slog.Info("...", "level", "info") and logcat showed
+// the message with no attributes at all.
+func TestACallersOwnLevelAttrSurvives(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	newLogger(rec, slog.LevelInfo).Info("probe", "level", "info", "time", "soon")
+
+	got := rec.only(t).msg
+
+	for _, want := range []string{"level=info", "time=soon"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("message %q lost the caller's %q", got, want)
+		}
+	}
+
+	// And slog's own are still gone: the built-in level renders as a
+	// bare word like INFO, never as the caller's value.
+	if strings.Contains(got, "level=INFO") {
+		t.Errorf("message %q carries slog's own level", got)
+	}
+}
+
+// TestLevelIsHonoured checks that Enabled reaches the delegate.
+func TestLevelIsHonoured(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	log := newLogger(rec, slog.LevelWarn)
+
+	log.Info("not this one")
+	log.Warn("this one")
+
+	if got := rec.only(t).msg; !strings.Contains(got, "this one") {
+		t.Errorf("wrong record survived: %q", got)
+	}
+}
+
+// TestGroupsAndAttrsSurvive covers the half of slog.Handler this
+// delegates rather than implements -- the reason it delegates at all.
+func TestGroupsAndAttrsSurvive(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	log := newLogger(rec, slog.LevelInfo).
+		With("component", "player").
+		WithGroup("track")
+
+	log.Info("loaded", "path", "/sdcard/Music/a.flac")
+
+	got := rec.only(t).msg
+
+	for _, want := range []string{
+		"component=player",
+		"track.path=/sdcard/Music/a.flac",
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("message %q is missing %q", got, want)
+		}
+	}
+}
+
+// TestDerivedHandlersDoNotInterleave is why derive shares the buffer's
+// mutex rather than taking a new one.
+//
+// Two loggers derived from one write into the same buffer, so a second
+// mutex would guard nothing and a concurrent pair would splice each
+// other's bytes into a single line -- which reads as corrupted logs
+// under load and as nothing at all in a test that logs once.
+func TestDerivedHandlersDoNotInterleave(t *testing.T) {
+	t.Parallel()
+
+	rec := &recorder{}
+	base := newLogger(rec, slog.LevelInfo)
+
+	var wg sync.WaitGroup
+
+	for i := range 8 {
+		wg.Add(1)
+
+		go func() {
+			defer wg.Done()
+
+			log := base.With("worker", i).WithGroup("g")
+			for range 50 {
+				log.Info("tick", "n", i)
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	rec.mu.Lock()
+	defer rec.mu.Unlock()
+
+	if len(rec.entries) != 8*50 {
+		t.Fatalf("got %d entries, want %d", len(rec.entries), 8*50)
+	}
+
+	for _, e := range rec.entries {
+		if strings.Count(e.msg, "msg=tick") != 1 {
+			t.Fatalf("interleaved line: %q", e.msg)
+		}
+	}
+}
+
+// TestChunkLeavesShortLinesAlone is the common case: no numbering
+// appears on a record that was never going to be truncated.
+func TestChunkLeavesShortLinesAlone(t *testing.T) {
+	t.Parallel()
+
+	got := androidlog.Chunk("msg=short")
+
+	if len(got) != 1 || got[0] != "msg=short" {
+		t.Errorf("Chunk(short) = %q, want the input unchanged", got)
+	}
+}
+
+// TestChunkSplitsWhatWouldBeTruncated covers the case liblog drops
+// silently.
+func TestChunkSplitsWhatWouldBeTruncated(t *testing.T) {
+	t.Parallel()
+
+	const n = 9000
+
+	long := strings.Repeat("x", n)
+	parts := androidlog.Chunk(long)
+
+	if len(parts) < 2 {
+		t.Fatalf("a %d-byte line was not split", n)
+	}
+
+	var payload strings.Builder
+
+	for i, p := range parts {
+		if len(p) > 4000 {
+			t.Errorf("part %d is %d bytes, over liblog's entry", i, len(p))
+		}
+
+		_, rest, found := strings.Cut(p, ") ")
+		if !found {
+			t.Fatalf("part %d carries no (n/m) marker: %q", i, p)
+		}
+
+		payload.WriteString(rest)
+	}
+
+	if payload.String() != long {
+		t.Errorf("the parts do not reassemble into the input")
+	}
+}

backend/config/config.go

@@ -303,6 +303,24 @@ func (c *Config) GetLibraryDirectory() string {
 	return string(c.Library.DirectoryPath)
 }
 
+// A rejected setter puts the old value back, and that is not tidiness
+// (#231).  Save validates the *whole* config, so a value left behind by
+// a failed write does not merely fail its own call: it fails every
+// later save, of every unrelated setting, silently and for the rest of
+// the session.  Nothing reaches disk, so a restart clears it -- which
+// is exactly what makes the fault hard to see and impossible to report.
+//
+// The setters below that assign and then validate therefore snapshot
+// the field first and restore it on the error path.  SetLibraryDirectory
+// is the other safe shape and the better one where the value can be
+// built on its own: it validates a candidate *before* assigning
+// anything, so there is nothing to undo.
+//
+// Not every setter needs either.  A bool, an int64 and the shortcut
+// bindings pass through no validation that can reject them, and
+// SetViewVisible refuses an unknown, non-hideable or launch-page view
+// up front, so GeneralConfig.Validate never sees one it would fail on.
+
 // SetLibraryDirectory validates and saves a new library directory,
 // then emits the LibraryConfigChanged event so listeners (e.g. the
 // Library scanner) can react.
@@ -360,11 +378,14 @@ func (c *Config) SetScanConcurrency(mode string) error {
 		c.Library.ApplyDefaults()
 	}
 
+	previous := c.Library.ScanConcurrency
 	c.Library.ScanConcurrency = library.ScanConcurrency(
 		mode,
 	)
 
 	if err := c.Library.Validate(); err != nil {
+		c.Library.ScanConcurrency = previous
+
 		return fmt.Errorf(
 			"invalid scan concurrency mode: %w", err,
 		)
@@ -455,9 +476,12 @@ func (c *Config) SetThemeAccentColor(
 		c.Theme.ApplyDefaults()
 	}
 
+	previous := c.Theme.AccentColor
 	c.Theme.AccentColor = color
 
 	if err := c.Theme.Validate(); err != nil {
+		c.Theme.AccentColor = previous
+
 		return fmt.Errorf(
 			"invalid theme accent color: %w", err,
 		)
@@ -488,9 +512,12 @@ func (c *Config) SetThemeBackgroundShade(
 		c.Theme.ApplyDefaults()
 	}
 
+	previous := c.Theme.BackgroundShade
 	c.Theme.BackgroundShade = theme.BackgroundShade(shade)
 
 	if err := c.Theme.Validate(); err != nil {
+		c.Theme.BackgroundShade = previous
+
 		return fmt.Errorf(
 			"invalid theme background shade: %w", err,
 		)
@@ -544,9 +571,12 @@ func (c *Config) SetDefaultPage(page string) error {
 		c.General.ApplyDefaults()
 	}
 
+	previous := c.General.DefaultPage
 	c.General.DefaultPage = View(page)
 
 	if err := c.General.Validate(); err != nil {
+		c.General.DefaultPage = previous
+
 		return fmt.Errorf(
 			"invalid default page: %w", err,
 		)
@@ -591,9 +621,12 @@ func (c *Config) SetQueueFallback(mode string) error {
 		c.General.ApplyDefaults()
 	}
 
+	previous := c.General.QueueFallback
 	c.General.QueueFallback = QueueFallback(mode)
 
 	if err := c.General.Validate(); err != nil {
+		c.General.QueueFallback = previous
+
 		return fmt.Errorf(
 			"invalid queue fallback: %w", err,
 		)
@@ -666,6 +699,49 @@ func (c *Config) SetAllowMeteredCatalogDownload(allow bool) error {
 	return nil
 }
 
+// GetPopupVolume reports whether the bottom bar's volume control is a
+// click-to-open popup rather than an inline slider (#42).
+func (c *Config) GetPopupVolume() bool {
+	if c.General == nil {
+		return false
+	}
+
+	return c.General.PopupVolume
+}
+
+// SetPopupVolume saves the volume control's presentation.
+//
+// Nothing to validate: both values are legal at every width, and the
+// frontend additionally stands the inline slider down below the phone
+// breakpoint whatever this says, because that is about room rather than
+// about preference.
+func (c *Config) SetPopupVolume(popup bool) error {
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	c.General.PopupVolume = popup
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf(
+			"could not save config: %w", err,
+		)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"PopupVolume": popup,
+		},
+	)
+
+	c.logger.Info("volume control presentation updated", "popup", popup)
+
+	return nil
+}
+
 // GetViewVisibility reports which primary views the sidebar should
 // show, answered for every known view rather than only the ones the
 // config mentions -- so the frontend filters on a value and never has
@@ -758,9 +834,12 @@ func (c *Config) SetTrackListColumns(
 		c.TrackList = &tracklist.Config{}
 	}
 
+	previous := c.TrackList.Columns
 	c.TrackList.Columns = columns
 
 	if err := c.TrackList.Validate(); err != nil {
+		c.TrackList.Columns = previous
+
 		return fmt.Errorf(
 			"invalid track-list columns: %w", err,
 		)
@@ -858,9 +937,12 @@ func (c *Config) SetFavoritesIconStyle(
 		c.Favorites.ApplyDefaults()
 	}
 
+	previous := c.Favorites.IconStyle
 	c.Favorites.IconStyle = favorites.IconStyle(style)
 
 	if err := c.Favorites.Validate(); err != nil {
+		c.Favorites.IconStyle = previous
+
 		return fmt.Errorf(
 			"invalid favorites icon style: %w", err,
 		)

backend/config/emit_test.go

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

backend/config/general.go

@@ -54,6 +54,16 @@ type GeneralConfig struct {
 	// so an existing config with no such key refuses by default rather
 	// than needing a migration to become careful.
 	AllowMeteredCatalogDownload bool `toml:"AllowMeteredCatalogDownload"`
+	// PopupVolume draws the bottom bar's volume as a click-to-open popup
+	// instead of a slider that is always there (#42).
+	//
+	// The polarity is the rule this file already states twice: **the
+	// zero value is the intended answer**. Inline is the new default, so
+	// the flag has to name the *other* choice — an `InlineVolume bool`
+	// would default to false and give every existing install the popup
+	// this issue exists to stop being the only option, and would need a
+	// migration to say otherwise.
+	PopupVolume bool `toml:"PopupVolume"`
 }
 
 // ApplyDefaults fills zero-value fields with sensible defaults.

backend/config/setter_rollback_test.go

@@ -0,0 +1,262 @@
+package config
+
+import (
+	"log/slog"
+	"path/filepath"
+	"testing"
+
+	"yellowjacket/backend/library"
+	"yellowjacket/backend/tracklist"
+)
+
+// newSavableConfig builds a loaded, valid config in a temp directory,
+// so Save() writes rather than refusing with errSaveBeforeLoad.
+//
+// The library directory is real and set, because Config.Validate only
+// validates the Library section when DirectoryPath is non-empty -- an
+// empty one would hide a poisoned ScanConcurrency from the whole-config
+// save that is the symptom under test.
+func newSavableConfig(t *testing.T) *Config {
+	t.Helper()
+
+	c := &Config{
+		logger:   slog.Default(),
+		filePath: filepath.Join(t.TempDir(), "config.toml"),
+		Library: &library.Config{
+			DirectoryPath: library.Directory(t.TempDir()),
+		},
+	}
+
+	c.applyDefaults()
+
+	if err := c.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	if err := c.Save(); err != nil {
+		t.Fatalf("Save() on a fresh config error: %v", err)
+	}
+
+	return c
+}
+
+// TestSetterRejectionDoesNotPoisonTheConfig is the whole of #231.
+//
+// Every setter here assigns to the in-memory config and then validates.
+// When the validation rejects the argument, the rejected value has to go
+// back -- not because the caller sees it (it gets an error either way),
+// but because Config.Save() validates the *whole* config.  A value left
+// behind by a failed setter therefore fails every later save, of every
+// unrelated setting, silently and for the rest of the session.
+//
+// So each case asserts three things in order: the setter reports the
+// error, the getter still reports the old value, and an unrelated save
+// still works.  The third is the one the user feels.
+func TestSetterRejectionDoesNotPoisonTheConfig(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		// reject calls the setter with an argument its own Validate
+		// refuses.
+		reject func(*Config) error
+		// read reports the value the setter writes, so the rollback is
+		// asserted on the config rather than only on the save.
+		read func(*Config) string
+	}{
+		{
+			name: "scan concurrency",
+			reject: func(c *Config) error {
+				return c.SetScanConcurrency("telepathy")
+			},
+			read: (*Config).GetScanConcurrency,
+		},
+		{
+			name: "theme accent colour",
+			reject: func(c *Config) error {
+				return c.SetThemeAccentColor("not-a-hex")
+			},
+			read: (*Config).GetThemeAccentColor,
+		},
+		{
+			name: "theme background shade",
+			reject: func(c *Config) error {
+				return c.SetThemeBackgroundShade("chartreuse")
+			},
+			read: (*Config).GetThemeBackgroundShade,
+		},
+		{
+			name: "default page",
+			reject: func(c *Config) error {
+				return c.SetDefaultPage("nowhere")
+			},
+			read: (*Config).GetDefaultPage,
+		},
+		{
+			name: "queue fallback",
+			reject: func(c *Config) error {
+				return c.SetQueueFallback("improvise")
+			},
+			read: (*Config).GetQueueFallback,
+		},
+		{
+			name: "favorites icon style",
+			reject: func(c *Config) error {
+				return c.SetFavoritesIconStyle("asterisk")
+			},
+			read: (*Config).GetFavoritesIconStyle,
+		},
+		{
+			name: "track-list columns",
+			reject: func(c *Config) error {
+				// titleArtist is a drawing definition, not a
+				// configurable column (#197), so it is exactly what
+				// the frontend used to be able to send.
+				return c.SetTrackListColumns([]tracklist.Column{
+					{ID: "titleArtist"},
+				})
+			},
+			read: func(c *Config) string {
+				return columnIDs(c.GetTrackListColumns())
+			},
+		},
+		{
+			name: "track-list columns, duplicated",
+			reject: func(c *Config) error {
+				// The route #197 closed was one invalid id; a
+				// duplicate is the one still reachable from a client
+				// that assembles the list itself.
+				return c.SetTrackListColumns([]tracklist.Column{
+					{ID: tracklist.ColTrackName},
+					{ID: tracklist.ColTrackName},
+				})
+			},
+			read: func(c *Config) string {
+				return columnIDs(c.GetTrackListColumns())
+			},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			c := newSavableConfig(t)
+			before := tc.read(c)
+
+			if err := tc.reject(c); err == nil {
+				t.Fatal("setter accepted an invalid value, want an error")
+			}
+
+			if after := tc.read(c); after != before {
+				t.Errorf(
+					"value after a rejected write = %q, want the previous %q",
+					after, before,
+				)
+			}
+
+			// The symptom: an unrelated setting can no longer be saved.
+			if err := c.SetPopupVolume(true); err != nil {
+				t.Errorf("an unrelated setter failed after a rejected write: %v", err)
+			}
+
+			if err := c.Save(); err != nil {
+				t.Errorf("Save() failed after a rejected write: %v", err)
+			}
+		})
+	}
+}
+
+// TestRejectedSetterLeavesNothingOnDisk pairs with the sweep above: the
+// rollback must not be undone by what the file already holds, so a
+// config reloaded from disk after a rejected write agrees with memory.
+func TestRejectedSetterLeavesNothingOnDisk(t *testing.T) {
+	t.Parallel()
+
+	c := newSavableConfig(t)
+
+	if err := c.SetThemeAccentColor("#123456"); err != nil {
+		t.Fatalf("SetThemeAccentColor() error: %v", err)
+	}
+
+	if err := c.SetThemeAccentColor("not-a-hex"); err == nil {
+		t.Fatal("SetThemeAccentColor accepted a non-colour, want an error")
+	}
+
+	reloaded := &Config{logger: slog.Default(), filePath: c.filePath}
+	reloaded.applyDefaults()
+
+	if err := reloaded.Load(); err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+
+	if got := reloaded.GetThemeAccentColor(); got != "#123456" {
+		t.Errorf("accent colour on disk = %q, want %q", got, "#123456")
+	}
+
+	if c.GetThemeAccentColor() != reloaded.GetThemeAccentColor() {
+		t.Errorf(
+			"in-memory accent %q disagrees with disk %q after a rejected write",
+			c.GetThemeAccentColor(), reloaded.GetThemeAccentColor(),
+		)
+	}
+}
+
+// TestSetLibraryDirectoryValidatesBeforeAssigning pins the precedent the
+// seven rolled-back setters follow: this one has always built and
+// validated a candidate before assigning, so a bad path never reaches
+// the config at all.
+func TestSetLibraryDirectoryValidatesBeforeAssigning(t *testing.T) {
+	t.Parallel()
+
+	c := newSavableConfig(t)
+	before := c.GetLibraryDirectory()
+
+	if err := c.SetLibraryDirectory(filepath.Join(t.TempDir(), "no-such-dir")); err == nil {
+		t.Fatal("SetLibraryDirectory accepted a missing directory, want an error")
+	}
+
+	if after := c.GetLibraryDirectory(); after != before {
+		t.Errorf("library directory = %q, want the previous %q", after, before)
+	}
+
+	if err := c.Save(); err != nil {
+		t.Errorf("Save() failed after a rejected library directory: %v", err)
+	}
+}
+
+// TestSetViewVisibleRefusesBeforeAssigning covers the other setter left
+// out of the rollback pass: it guards its own argument up front, so
+// GeneralConfig.Validate never sees a view it would reject.
+func TestSetViewVisibleRefusesBeforeAssigning(t *testing.T) {
+	t.Parallel()
+
+	c := newSavableConfig(t)
+
+	if err := c.SetViewVisible("no-such-view", false); err == nil {
+		t.Fatal("SetViewVisible accepted an unknown view, want an error")
+	}
+
+	if err := c.SetViewVisible(c.GetDefaultPage(), false); err == nil {
+		t.Fatal("SetViewVisible hid the launch page, want an error")
+	}
+
+	if err := c.Save(); err != nil {
+		t.Errorf("Save() failed after a refused view visibility change: %v", err)
+	}
+}
+
+// columnIDs renders a column list for comparison in the table above.
+func columnIDs(cols []tracklist.Column) string {
+	ids := make([]byte, 0, len(cols)*8)
+
+	for i, col := range cols {
+		if i > 0 {
+			ids = append(ids, ',')
+		}
+
+		ids = append(ids, col.ID...)
+	}
+
+	return string(ids)
+}

backend/database/database_test.go

@@ -662,19 +662,19 @@ func TestSmartPlaylistColumns(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// Migration 10 — play history tracking
+// Listening events tracking
 // ---------------------------------------------------------------------------
 
-func TestPlayHistoryTable(t *testing.T) {
+func TestListeningEventsTable(t *testing.T) {
 	t.Parallel()
 
 	db := NewTestDB(t)
 
-	// Verify play_history table exists.
+	// Verify listening_events table exists.
 	var tableCount int64
 
 	tblRows, err := db.QueryContext(
-		"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='play_history'",
+		"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='listening_events'",
 	)
 	if err != nil {
 		t.Fatalf("query sqlite_master: %v", err)
@@ -695,12 +695,14 @@ func TestPlayHistoryTable(t *testing.T) {
 	_ = tblRows.Close()
 
 	if tableCount != 1 {
-		t.Errorf("play_history table count = %d, want 1", tableCount)
+		t.Errorf("listening_events table count = %d, want 1", tableCount)
 	}
 
-	// Verify audio_files has play_count and last_played columns.
+	// Verify audio_files has the denormalized listening counters.
 	hasPlayCount := false
 	hasLastPlayed := false
+	hasSkipCount := false
+	hasLastSkipped := false
 
 	colRows, err := db.QueryContext("PRAGMA table_info(audio_files)")
 	if err != nil {
@@ -732,6 +734,14 @@ func TestPlayHistoryTable(t *testing.T) {
 		if name == "last_played" {
 			hasLastPlayed = true
 		}
+
+		if name == "skip_count" {
+			hasSkipCount = true
+		}
+
+		if name == "last_skipped" {
+			hasLastSkipped = true
+		}
 	}
 
 	_ = colRows.Close()
@@ -744,6 +754,14 @@ func TestPlayHistoryTable(t *testing.T) {
 		t.Error("audio_files missing last_played column")
 	}
 
+	if !hasSkipCount {
+		t.Error("audio_files missing skip_count column")
+	}
+
+	if !hasLastSkipped {
+		t.Error("audio_files missing last_skipped column")
+	}
+
 	// Verify track_metadata VIEW includes play_count and last_played.
 	viewCols := map[string]bool{}
 
@@ -783,7 +801,7 @@ func TestPlayHistoryTable(t *testing.T) {
 		t.Error("track_metadata VIEW missing last_played column")
 	}
 
-	// Round-trip: insert a play_history row and verify play_count update.
+	// Round-trip: insert a listening_events row and verify play_count update.
 	// First, set up test data. The test DB already has library id=0.
 	InsertTestTrack(t, db, TestTrack{
 		FilePath:    "/test/play_history.mp3",
@@ -821,12 +839,12 @@ func TestPlayHistoryTable(t *testing.T) {
 		t.Errorf("initial play_count = %d, want 0", playCount)
 	}
 
-	// Insert a play_history row and update play_count.
+	// Insert a listening_events row (kind defaults to 'complete').
 	_, err = db.ExecContext(
-		"INSERT INTO play_history (audio_file_id) VALUES (1)",
+		"INSERT INTO listening_events (audio_file_id, kind) VALUES (1, 'complete')",
 	)
 	if err != nil {
-		t.Fatalf("insert play_history: %v", err)
+		t.Fatalf("insert listening_events: %v", err)
 	}
 
 	_, err = db.ExecContext(

backend/database/playlistphantoms.go

@@ -0,0 +1,125 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log/slog"
+)
+
+// Preserving a playlist entry across the loss of its track is two
+// statements, not one, and the split is not tidiness -- it is what
+// makes the important half work in the situation that needs it most.
+//
+// `playlist_tracks.audio_file_id` is ON DELETE SET NULL, so an entry
+// outlives its file as an id-less row that says nothing about what the
+// user put in the playlist.  The phantom_* columns carry the answer
+// across and ResolvePhantomTracksAfterScan re-links them afterwards --
+// but only if something fills them *before* the rows go.
+//
+// The two halves are not equally important and are not equally
+// available:
+//
+//   - **phantom_file_path is the one that matters.**
+//     ResolvePhantomTracksAfterScan matches it against
+//     `audio_files.file_path`, so without it an entry can never be
+//     re-linked and the playlist is empty for good.  It comes straight
+//     off `audio_files`, whose `file_path` is the table's natural key
+//     and has been present in every shape it has ever had -- including
+//     the pre-013 stub of `(id, file_path, recording_id)`.
+//   - The rest is *display* for a phantom entry before a rescan
+//     re-links it, and it comes from the `track_metadata` view, which
+//     is the one definition of a track row and not worth restating.
+//
+// Reading the view is what cannot be relied on here, and that is the
+// whole reason for the split.  This runs *before* applySchema, which is
+// precisely the moment the schema is inconsistent: the view is whatever
+// the last launch's schema declared, while `audio_files` is whatever
+// the launch before that left behind.  A view over columns the table no
+// longer has is not merely empty -- `pragma_table_info` on it *errors*,
+// and so does selecting from it.  `cmd/indexbuild`'s fixture is exactly
+// that shape and is what caught this.
+//
+// COALESCE keeps an existing phantom value in both halves: an entry
+// already phantom is one whose file went missing in an earlier pass,
+// and its recorded metadata is the only copy left.  Overwriting that
+// from a NULL join erases the rows this exists to protect.
+const (
+	preservePhantomPathSQL = `
+		UPDATE playlist_tracks
+		SET phantom_file_path = COALESCE(phantom_file_path, (
+			SELECT af.file_path FROM audio_files af
+			WHERE af.id = playlist_tracks.audio_file_id
+		))
+		WHERE audio_file_id IS NOT NULL
+	`
+
+	preservePhantomDisplaySQL = `
+		UPDATE playlist_tracks
+		SET
+			phantom_title = COALESCE(phantom_title, (
+				SELECT tm.title FROM track_metadata tm
+				WHERE tm.id = playlist_tracks.audio_file_id
+			)),
+			phantom_artist = COALESCE(phantom_artist, (
+				SELECT tm.artist_name FROM track_metadata tm
+				WHERE tm.id = playlist_tracks.audio_file_id
+			)),
+			phantom_album = COALESCE(phantom_album, (
+				SELECT tm.album FROM track_metadata tm
+				WHERE tm.id = playlist_tracks.audio_file_id
+			)),
+			phantom_duration_ms = COALESCE(phantom_duration_ms, (
+				SELECT af.length_milliseconds FROM audio_files af
+				WHERE af.id = playlist_tracks.audio_file_id
+			)),
+			phantom_genre = COALESCE(phantom_genre, (
+				SELECT tm.genre FROM track_metadata tm
+				WHERE tm.id = playlist_tracks.audio_file_id
+			)),
+			phantom_cover_art_path = COALESCE(phantom_cover_art_path, (
+				SELECT tm.cover_art_path FROM track_metadata tm
+				WHERE tm.id = playlist_tracks.audio_file_id
+			))
+		WHERE audio_file_id IS NOT NULL
+	`
+)
+
+// PreservePlaylistPhantoms records every linked playlist entry's track
+// metadata on the entry itself, so the entry survives the rows being
+// deleted underneath it.
+//
+// Every path that empties `audio_files` must call this first, inside
+// the same transaction as the delete.  There are two such paths and
+// they had drifted: the full rescan in backend/library did this and the
+// stale-shape retire in this package did not, so the *documented*
+// repair ("delete and rescan") preserved playlists while the automatic
+// one that exists to spare the user that work silently emptied them.
+//
+// The display half is skipped, with a warning, when `track_metadata`
+// cannot answer -- see the note above.  Skipping it costs a phantom
+// entry its title until a rescan re-links it; skipping the path half
+// would cost the entry outright, so that one is an error.
+func PreservePlaylistPhantoms(
+	ctx context.Context, tx *sql.Tx, logger *slog.Logger,
+) error {
+	if _, err := tx.ExecContext(ctx, preservePhantomPathSQL); err != nil {
+		return fmt.Errorf(
+			"could not preserve playlist track file paths: %w", err,
+		)
+	}
+
+	if _, err := tx.ExecContext(ctx, preservePhantomDisplaySQL); err != nil {
+		// A failed statement does not roll back a SQLite transaction,
+		// so the path half above stands and the entries remain
+		// re-linkable.
+		logger.Warn(
+			"could not record display metadata for playlist entries; "+
+				"they will be re-linked by the next scan but read as "+
+				"unknown until then",
+			"err", err,
+		)
+	}
+
+	return nil
+}

backend/database/sql/queries/albums.sql

@@ -40,7 +40,8 @@ WHERE id = ? AND (mbid IS NULL OR mbid = '');
 -- name: GetAlbumsWithPendingReleaseMBID :many
 SELECT id, pending_release_mbid FROM albums
 WHERE pending_release_mbid IS NOT NULL AND pending_release_mbid != ''
-  AND (mbid IS NULL OR mbid = '');
+  AND (mbid IS NULL OR mbid = '')
+LIMIT ?;
 
 -- name: DeleteAlbum :exec
 DELETE FROM albums WHERE id = ?;

backend/database/sql/schemas/audio_files.sql

@@ -68,8 +68,14 @@ CREATE TABLE IF NOT EXISTS audio_files (
   -- compared against the on-disk mtime during a scan to detect files
   -- another application retagged in place.
   modified_at        INTEGER NOT NULL DEFAULT 0,
+  -- Listening counts, denormalized from listening_events so the hot
+  -- read path (track list sort, shelves, smart playlists) never joins
+  -- a log table.  Authored: a rescan cannot rebuild them.  This is the
+  -- "MIXED KIND" half of audio_files the datamap notes.
   play_count         INTEGER NOT NULL DEFAULT 0,
   last_played        DATETIME,
+  skip_count         INTEGER NOT NULL DEFAULT 0,
+  last_skipped       DATETIME,
   tag_status         TEXT NOT NULL DEFAULT 'untagged'
     CHECK(tag_status IN (
       'untagged', 'auto_matched', 'user_confirmed', 'user_skipped_permanent'

backend/database/sql/schemas/download_items.sql

@@ -45,8 +45,6 @@ CREATE INDEX IF NOT EXISTS idx_download_items_live
 CREATE INDEX IF NOT EXISTS idx_download_items_state
     ON download_items(state);
 
--- idx_download_items_download is deliberately NOT declared here: on an
--- existing database this table already exists at schema-pass time with
--- its old column still named request_id, so an inline CREATE INDEX on
--- download_id would fail outright. See ensureDownloadIndexes in
--- backend/database/download_rename_migration.go.
+-- ListDownloadItemsForDownload filters on the parent download.
+CREATE INDEX IF NOT EXISTS idx_download_items_download
+    ON download_items(download_id);

backend/database/sql/schemas/download_requests.sql

@@ -66,14 +66,11 @@ CREATE TABLE IF NOT EXISTS download_requests (
     FOREIGN KEY(parent_id) REFERENCES download_requests(id) ON DELETE CASCADE
 );
 
--- idx_download_requests_{due,entity,parent} are deliberately NOT
--- declared here. This table name is reused from the old one-shot
--- attempt table (also called download_requests before the Want/Request
--- rename), so on an existing database this CREATE TABLE is a no-op
--- against a table that, at schema-pass time, is still shaped like the
--- OLD attempts table and lacks these columns entirely — an inline
--- CREATE INDEX here would fail outright rather than just no-op. See
--- migrateDownloadRename/ensureDownloadIndexes in
--- backend/database/download_rename_migration.go, which create these
--- once the rename has actually happened (or immediately, on a fresh
--- database where the columns exist from the start).
+CREATE INDEX IF NOT EXISTS idx_download_requests_due
+    ON download_requests(state, next_try_at);
+
+CREATE INDEX IF NOT EXISTS idx_download_requests_entity
+    ON download_requests(entity, state);
+
+CREATE INDEX IF NOT EXISTS idx_download_requests_parent
+    ON download_requests(parent_id) WHERE parent_id IS NOT NULL;

backend/database/sql/schemas/listening_events.sql

@@ -0,0 +1,42 @@
+-- One row per track *exit*, three ways a listen can end: it reached
+-- the end, it was heard enough to count and then skipped past, or it
+-- was abandoned for another track before anyone had really listened.
+--
+-- This is the source of truth for listening behaviour.  The
+-- denormalized `play_count` / `last_played` / `skip_count` /
+-- `last_skipped` on audio_files are materialized from it, because the
+-- hot read path (track-list sort, the shelves, smart playlists) must
+-- not join a log that grows by one row per song forever.
+--
+-- `kind` is the classification, applied at write time:
+--
+--   complete   the track reached its natural end, or was skipped in
+--              its tail window (the last few seconds of a long fade).
+--   play       the scrobble threshold was heard — half the track or
+--              four minutes, whichever is less — and the user moved on
+--              before the end.
+--   skip       the user moved to a different track before that.
+--
+-- `position_seconds` / `duration_seconds` are the raw reading the
+-- classification was made from, kept so a future re-tune of the
+-- threshold does not need the events re-recorded.  0/0 on a row means
+-- "not captured for this event" (e.g. a natural finish recorded before
+-- these columns existed), not "a zero-second track".
+CREATE TABLE IF NOT EXISTS listening_events (
+    id               INTEGER PRIMARY KEY,
+    audio_file_id    INTEGER NOT NULL,
+    kind             TEXT NOT NULL DEFAULT 'complete'
+                     CHECK (kind IN ('complete', 'play', 'skip')),
+    position_seconds INTEGER NOT NULL DEFAULT 0,
+    duration_seconds INTEGER NOT NULL DEFAULT 0,
+    occurred_at      DATETIME NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY(audio_file_id) REFERENCES audio_files(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_listening_events_audio_file_id
+    ON listening_events(audio_file_id);
+
+-- "What did I listen to this month" walks this, rather than the
+-- per-track index above.
+CREATE INDEX IF NOT EXISTS idx_listening_events_occurred_at
+    ON listening_events(occurred_at);

backend/database/sql/schemas/play_history.sql

@@ -1,9 +0,0 @@
-CREATE TABLE IF NOT EXISTS play_history (
-    id INTEGER PRIMARY KEY,
-    audio_file_id INTEGER NOT NULL,
-    played_at DATETIME NOT NULL DEFAULT (datetime('now')),
-    FOREIGN KEY(audio_file_id) REFERENCES audio_files(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_play_history_audio_file_id
-    ON play_history(audio_file_id);

backend/database/sql/schemas/queue.sql

@@ -1,18 +1,15 @@
 CREATE TABLE IF NOT EXISTS queue (
     id INTEGER PRIMARY KEY CHECK(id = 1),
-    source_playlist_id INTEGER,
     current_position INTEGER NOT NULL DEFAULT 0,
     shuffle_mode BOOLEAN NOT NULL DEFAULT false,
     repeat_mode TEXT NOT NULL DEFAULT 'off',
     shuffle_order TEXT,
-    -- source_playlist_id above is unused dead weight (nothing has ever
-    -- written it a nonzero value); source_type/source_id/source_label
-    -- below are its generalized replacement, covering albums, playlists,
-    -- smart playlists, genres and artists rather than playlists alone.
+    -- What the queue was built from ("Playing from: X"): an album,
+    -- playlist, smart playlist, genre or artist, identified by the id
+    -- that source_type's namespace gives it.
     source_type TEXT NOT NULL DEFAULT '',
     source_id INTEGER NOT NULL DEFAULT 0,
-    source_label TEXT NOT NULL DEFAULT '',
-    FOREIGN KEY(source_playlist_id) REFERENCES playlists(id) ON DELETE SET NULL
+    source_label TEXT NOT NULL DEFAULT ''
 );
 
 -- Singleton row: there is exactly one playback queue.

backend/database/sql/schemas/tagging_items.sql

@@ -26,17 +26,10 @@ CREATE TABLE IF NOT EXISTS tagging_items (
   -- complete rip of their own directory.  parent_group_key is the
   -- original folder group they were split from.
   --
-  -- These two columns are declared LAST, after created_at, even
-  -- though that reads oddly next to the rest of the table: sql/
-  -- migrations/0001 brings a pre-existing tagging_items up to date
-  -- with `ALTER TABLE ADD COLUMN`, which SQLite always appends at
-  -- the end of the column list.  A fresh install (this file) and an
-  -- upgraded database (this file + the migration) must end up with
-  -- IDENTICAL column order, because sqlc-generated `SELECT *` scans
-  -- (e.g. GetTaggingItem) bind columns positionally — see the
-  -- schema/migration column-order test in database_test.go.  Put
-  -- new columns wherever reads best when adding a table for the
-  -- first time; append-only from the second migration on.
+  -- These columns are appended after created_at rather than grouped
+  -- with the rest of the row: sqlc's `SELECT *` scans (GetTaggingItem)
+  -- bind column order positionally, so new columns always go at the
+  -- end.
   synthetic               INTEGER NOT NULL DEFAULT 0,
   parent_group_key        TEXT NOT NULL DEFAULT '',
   -- album_artist_conflict latches to 1 the first time two tracks
@@ -58,10 +51,3 @@ CREATE INDEX IF NOT EXISTS idx_tagging_items_library_status
 
 CREATE INDEX IF NOT EXISTS idx_tagging_items_status_pending
     ON tagging_items(library_id) WHERE status = 'pending';
-
--- idx_tagging_items_parent_group_key is NOT declared here on
--- purpose: this file runs unconditionally, before migrations, even
--- against a database that hasn't run 0001 yet — an index predicate
--- referencing parent_group_key would fail on that table.  It lives
--- solely in sql/migrations/0001_tagging_items_synthetic.sql, which
--- runs after the column exists either way (see database.go).

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

@@ -331,6 +331,7 @@ const getAlbumsWithPendingReleaseMBID = `-- name: GetAlbumsWithPendingReleaseMBI
 SELECT id, pending_release_mbid FROM albums
 WHERE pending_release_mbid IS NOT NULL AND pending_release_mbid != ''
   AND (mbid IS NULL OR mbid = '')
+LIMIT ?
 `
 
 type GetAlbumsWithPendingReleaseMBIDRow struct {
@@ -338,8 +339,8 @@ type GetAlbumsWithPendingReleaseMBIDRow struct {
 	PendingReleaseMbid sql.NullString
 }
 
-func (q *Queries) GetAlbumsWithPendingReleaseMBID(ctx context.Context) ([]GetAlbumsWithPendingReleaseMBIDRow, error) {
-	rows, err := q.db.QueryContext(ctx, getAlbumsWithPendingReleaseMBID)
+func (q *Queries) GetAlbumsWithPendingReleaseMBID(ctx context.Context, limit int64) ([]GetAlbumsWithPendingReleaseMBIDRow, error) {
+	rows, err := q.db.QueryContext(ctx, getAlbumsWithPendingReleaseMBID, limit)
 	if err != nil {
 		return nil, err
 	}

backend/database/sql/sqlcgen/audio_files.sql.go

@@ -39,7 +39,7 @@ INSERT INTO audio_files (
   ?, ?, ?, ?, ?, ?,
   ?, ?, ?, ?, ?
 )
-RETURNING id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, tag_status
+RETURNING id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, skip_count, last_skipped, tag_status
 `
 
 type CreateAudioFileParams struct {
@@ -135,6 +135,8 @@ func (q *Queries) CreateAudioFile(ctx context.Context, arg CreateAudioFileParams
 		&i.ModifiedAt,
 		&i.PlayCount,
 		&i.LastPlayed,
+		&i.SkipCount,
+		&i.LastSkipped,
 		&i.TagStatus,
 	)
 	return i, err
@@ -192,7 +194,7 @@ func (q *Queries) GetAllAudioFilePaths(ctx context.Context) ([]GetAllAudioFilePa
 
 const getAudioFile = `-- name: GetAudioFile :one
 
-SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, tag_status FROM audio_files WHERE id = ? LIMIT 1
+SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, skip_count, last_skipped, tag_status FROM audio_files WHERE id = ? LIMIT 1
 `
 
 // ---------------------------------------------------------------------
@@ -228,13 +230,15 @@ func (q *Queries) GetAudioFile(ctx context.Context, id int64) (AudioFile, error)
 		&i.ModifiedAt,
 		&i.PlayCount,
 		&i.LastPlayed,
+		&i.SkipCount,
+		&i.LastSkipped,
 		&i.TagStatus,
 	)
 	return i, err
 }
 
 const getAudioFileByPath = `-- name: GetAudioFileByPath :one
-SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, tag_status FROM audio_files WHERE file_path = ? LIMIT 1
+SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, skip_count, last_skipped, tag_status FROM audio_files WHERE file_path = ? LIMIT 1
 `
 
 func (q *Queries) GetAudioFileByPath(ctx context.Context, filePath string) (AudioFile, error) {
@@ -267,6 +271,8 @@ func (q *Queries) GetAudioFileByPath(ctx context.Context, filePath string) (Audi
 		&i.ModifiedAt,
 		&i.PlayCount,
 		&i.LastPlayed,
+		&i.SkipCount,
+		&i.LastSkipped,
 		&i.TagStatus,
 	)
 	return i, err
@@ -334,7 +340,7 @@ func (q *Queries) GetAudioFilesByPaths(ctx context.Context, paths []string) ([]G
 }
 
 const getAudioFilesInLibrary = `-- name: GetAudioFilesInLibrary :many
-SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, tag_status FROM audio_files WHERE library_id = ?
+SELECT id, file_path, library_id, file_type_id, length_milliseconds, sample_rate, bit_depth, channels, bitrate, file_size, title, artist_credit, artist_id, album_id, track_number, disc_number, total_tracks, year, composer, comment, recording_mbid, basename, group_key, modified_at, play_count, last_played, skip_count, last_skipped, tag_status FROM audio_files WHERE library_id = ?
 `
 
 func (q *Queries) GetAudioFilesInLibrary(ctx context.Context, libraryID int64) ([]AudioFile, error) {
@@ -373,6 +379,8 @@ func (q *Queries) GetAudioFilesInLibrary(ctx context.Context, libraryID int64) (
 			&i.ModifiedAt,
 			&i.PlayCount,
 			&i.LastPlayed,
+			&i.SkipCount,
+			&i.LastSkipped,
 			&i.TagStatus,
 		); err != nil {
 			return nil, err

backend/database/sql/sqlcgen/models.go

@@ -94,6 +94,8 @@ type AudioFile struct {
 	ModifiedAt         int64
 	PlayCount          int64
 	LastPlayed         sql.NullTime
+	SkipCount          int64
+	LastSkipped        sql.NullTime
 	TagStatus          string
 }
 
@@ -261,6 +263,15 @@ type Library struct {
 	AutotagWarningAcked int64
 }
 
+type ListeningEvent struct {
+	ID              int64
+	AudioFileID     int64
+	Kind            string
+	PositionSeconds int64
+	DurationSeconds int64
+	OccurredAt      time.Time
+}
+
 type Lyric struct {
 	AudioFileID   int64
 	Text          string
@@ -273,12 +284,6 @@ type LyricsIndex struct {
 	Lyrics string
 }
 
-type PlayHistory struct {
-	ID          int64
-	AudioFileID int64
-	PlayedAt    time.Time
-}
-
 type PlayerState struct {
 	ID                  int64
 	Volume              int64
@@ -312,15 +317,14 @@ type PlaylistTrack struct {
 }
 
 type Queue struct {
-	ID               int64
-	SourcePlaylistID sql.NullInt64
-	CurrentPosition  int64
-	ShuffleMode      bool
-	RepeatMode       string
-	ShuffleOrder     sql.NullString
-	SourceType       string
-	SourceID         int64
-	SourceLabel      string
+	ID              int64
+	CurrentPosition int64
+	ShuffleMode     bool
+	RepeatMode      string
+	ShuffleOrder    sql.NullString
+	SourceType      string
+	SourceID        int64
+	SourceLabel     string
 }
 
 type QueueTrack struct {

backend/database/staleshape.go

@@ -245,6 +245,13 @@ func dropDeferred(
 	ctx context.Context, db *sql.DB, logger *slog.Logger,
 	drop map[string]string,
 ) error {
+	// Asked before the transaction opens, because the answer is about
+	// which tables are live and that cannot change underneath us here.
+	preserve, err := shouldPreservePhantoms(ctx, db, drop)
+	if err != nil {
+		return err
+	}
+
 	tx, err := db.BeginTx(ctx, nil)
 	if err != nil {
 		return fmt.Errorf("could not begin the retire transaction: %w", err)
@@ -256,6 +263,22 @@ func dropDeferred(
 		return fmt.Errorf("could not defer foreign keys: %w", err)
 	}
 
+	// Before any drop, so every entry still has a track to read.  It is
+	// in this transaction rather than beside it because the preservation
+	// and the delete have to succeed or fail together: a commit that
+	// dropped the files without the phantoms is the bug, and a commit
+	// that wrote phantoms without dropping anything is a lie about rows
+	// that are still there.
+	if preserve {
+		logger.Info(
+			"preserving playlist entries across the retire of audio_files",
+		)
+
+		if err := PreservePlaylistPhantoms(ctx, tx, logger); err != nil {
+			return err
+		}
+	}
+
 	// Sorted, so a failure is reproducible.  Map order is random, and a
 	// bug that depends on which table happens to go first reproduces on
 	// one run in three and passes review on the other two -- which is
@@ -283,6 +306,38 @@ func dropDeferred(
 	return nil
 }
 
+// shouldPreservePhantoms reports whether this retire is about to take
+// `audio_files` out from under the playlists.
+//
+// The `playlist_tracks` check is not defensive padding.  This runs
+// *before* applySchema, which is the moment the schema is by definition
+// mid-repair, and the preservation reads a table it does not drop.  A
+// database old enough not to have it would otherwise fail here, and
+// failing here means the app does not open at all -- while nothing is
+// lost by skipping, since an absent `playlist_tracks` holds no
+// playlists to save.
+//
+// It deliberately does *not* ask after `track_metadata`.  Whether that
+// view can answer is PreservePlaylistPhantoms's own business, because a
+// view broken against an older `audio_files` is a state this function
+// cannot detect without hitting the same error it is trying to avoid:
+// pragma_table_info on such a view errors rather than reporting no
+// columns.
+func shouldPreservePhantoms(
+	ctx context.Context, db *sql.DB, drop map[string]string,
+) (bool, error) {
+	if _, going := drop["audio_files"]; !going {
+		return false, nil
+	}
+
+	cols, err := liveColumns(ctx, db, "playlist_tracks")
+	if err != nil {
+		return false, err
+	}
+
+	return len(cols) > 0, nil
+}
+
 // staleReason reports why a live table disagrees with its declaration,
 // or "" when it agrees.  A column the live table does not have is the
 // additive case; a column whose declared type changed is the one an

backend/database/staleshape_test.go

@@ -497,3 +497,180 @@ func TestParseCreateTablesReadsTheRealSchema(t *testing.T) {
 		}
 	}
 }
+
+// TestRetiringAudioFilesKeepsPlaylistContents is the symptom this
+// repair exists for: a playlist survived the retire as a row count and
+// nothing else.
+//
+// TestRetiringOwnedTablesDoesNotDangle already asserts the entry does
+// not keep a stale id, which is the *dangerous* half.  It is satisfied
+// just as well by an entry that says nothing at all, which is the
+// half that quietly emptied every playlist -- so this asserts what the
+// entry still knows, and specifically phantom_file_path, because that
+// is the column ResolvePhantomTracksAfterScan matches back against
+// audio_files.file_path.
+//
+// Note the seed drops `comment`, not `artist_credit`: the mutation has
+// to leave `track_metadata` standing, since a real launch reaches the
+// retire with the view the previous launch created.  A test that drops
+// the view first is testing the skip path, not this one.
+func TestRetiringAudioFilesKeepsPlaylistContents(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if _, err := db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		t.Fatalf("pragma: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	if _, err := db.ExecContext(ctx, `
+		INSERT INTO playlists (id, name) VALUES (1, 'keepme');
+		INSERT INTO libraries (id, name, path) VALUES (0, 'test', '/music');
+		INSERT INTO artists (id, name) VALUES (3, 'Aurora Fields');
+		INSERT INTO cover_art (id, file_path, mime_type)
+			VALUES (9, 'covers/7.jpg', 'image/jpeg');
+		INSERT INTO genres (id, name) VALUES (5, 'Ambient');
+		INSERT INTO albums (id, name, artist_id, cover_art_id)
+			VALUES (4, 'Tideline', 3, 9);
+		INSERT INTO audio_files
+			(id, file_path, file_type_id, length_milliseconds,
+			 title, artist_credit, artist_id, album_id)
+			VALUES (7, '/music/a.flac', 1, 1000,
+			        'Slack Water', 'Aurora Fields', 3, 4);
+		INSERT INTO file_genres (audio_file_id, genre_id) VALUES (7, 5);
+		INSERT INTO playlist_tracks (playlist_id, audio_file_id, position)
+			VALUES (1, 7, 0);
+		ALTER TABLE audio_files DROP COLUMN comment;
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	var (
+		path, title, artist, album, genre, cover sql.NullString
+		duration                                 sql.NullInt64
+	)
+
+	if err := db.QueryRowContext(ctx, `
+		SELECT phantom_file_path, phantom_title, phantom_artist,
+		       phantom_album, phantom_duration_ms, phantom_genre,
+		       phantom_cover_art_path
+		FROM playlist_tracks WHERE playlist_id = 1
+	`).Scan(&path, &title, &artist, &album, &duration, &genre, &cover); err != nil {
+		t.Fatalf("read the surviving entry: %v", err)
+	}
+
+	// The one that matters: without it the entry can never be re-linked
+	// by the rescan the retire itself provokes.
+	if path.String != "/music/a.flac" {
+		t.Fatalf(
+			"phantom_file_path is %q, want %q -- the playlist entry "+
+				"cannot be re-linked and the playlist is empty for good",
+			path.String, "/music/a.flac",
+		)
+	}
+
+	if title.String != "Slack Water" {
+		t.Errorf("phantom_title is %q, want %q", title.String, "Slack Water")
+	}
+
+	if artist.String != "Aurora Fields" {
+		t.Errorf("phantom_artist is %q, want %q", artist.String, "Aurora Fields")
+	}
+
+	if album.String != "Tideline" {
+		t.Errorf("phantom_album is %q, want %q", album.String, "Tideline")
+	}
+
+	if duration.Int64 != 1000 {
+		t.Errorf("phantom_duration_ms is %d, want 1000", duration.Int64)
+	}
+
+	if genre.String != "Ambient" {
+		t.Errorf("phantom_genre is %q, want %q", genre.String, "Ambient")
+	}
+
+	if cover.String != "covers/7.jpg" {
+		t.Errorf("phantom_cover_art_path is %q, want %q", cover.String, "covers/7.jpg")
+	}
+}
+
+// TestRetiringAudioFilesKeepsPathsWhenTheViewCannotAnswer is the case
+// that broke cmd/indexbuild: this repair runs *before* applySchema, so
+// `track_metadata` is whatever the last launch declared while
+// `audio_files` is whatever the launch before that left behind, and a
+// view over columns the table no longer has does not read as empty --
+// it errors.
+//
+// The pre-013 stub shape below is the real one that fixture carries.
+// What must survive is phantom_file_path, because `file_path` is the
+// table's natural key and has been in every shape it ever had; the
+// display columns are allowed to be absent, and the open must not fail.
+func TestRetiringAudioFilesKeepsPathsWhenTheViewCannotAnswer(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if _, err := db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		t.Fatalf("pragma: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	// The rows go in *after* the reshape: dropping audio_files with
+	// foreign keys on would fire the ON DELETE SET NULL and null the
+	// entry this test is about, which would pass for the wrong reason.
+	if _, err := db.ExecContext(ctx, `
+		DROP TABLE audio_files;
+		CREATE TABLE audio_files (
+			id           INTEGER PRIMARY KEY,
+			file_path    TEXT NOT NULL UNIQUE,
+			recording_id INTEGER
+		);
+		INSERT INTO playlists (id, name) VALUES (1, 'keepme');
+		INSERT INTO audio_files (id, file_path) VALUES (7, '/music/a.flac');
+		INSERT INTO playlist_tracks (playlist_id, audio_file_id, position)
+			VALUES (1, 7, 0);
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	// The symptom this guards: the repair must not turn a recoverable
+	// database into one the app refuses to open.
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf(
+			"the retire failed on a view it could not read, so the app "+
+				"would not open at all: %v", err,
+		)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	var path sql.NullString
+	if err := db.QueryRowContext(ctx,
+		"SELECT phantom_file_path FROM playlist_tracks WHERE playlist_id = 1",
+	).Scan(&path); err != nil {
+		t.Fatalf("read the surviving entry: %v", err)
+	}
+
+	if path.String != "/music/a.flac" {
+		t.Fatalf(
+			"phantom_file_path is %q, want %q -- the display half being "+
+				"unavailable must not cost the entry its one re-link key",
+			path.String, "/music/a.flac",
+		)
+	}
+}

backend/datamap/datamap.go

@@ -269,10 +269,11 @@ var tables = []Table{
 			"from owned files plus the LRCLIB backfill.",
 	},
 	{
-		Name: "play_history", Kind: Authored, Lifetime: Cascade,
-		Note: "Listening history. Authored, but intentionally cascades " +
-			"with its track — history for a file no longer in the library " +
-			"has nothing to point at.",
+		Name: "listening_events", Kind: Authored, Lifetime: Cascade,
+		Note: "Listening history, one row per track exit (complete, play " +
+			"or skip). Authored, but intentionally cascades with its " +
+			"track — history for a file no longer in the library has " +
+			"nothing to point at.",
 	},
 	{
 		Name: "player_state", Kind: Authored, Lifetime: Retained,

backend/datamap/datamap_test.go

@@ -212,14 +212,14 @@ func TestLifetimesMatchSchema(t *testing.T) {
 
 // Authored data is unrecoverable, so it must never be removed as a side
 // effect of deleting owned data.  Cascade is allowed only where the
-// catalog explains why (play_history, queue_tracks); this test pins the
+// catalog explains why (listening_events, queue_tracks); this test pins the
 // set so a new cascade onto authored data is a deliberate decision.
 func TestAuthoredCascadesAreDeliberate(t *testing.T) {
 	t.Parallel()
 
 	allowed := map[string]bool{
-		"play_history": true,
-		"queue_tracks": true,
+		"listening_events": true,
+		"queue_tracks":     true,
 
 		// Download history is scoped to the library it imported into.
 		// When that library is removed the files it acquired go with

backend/download/provider_ytdlp_test.go

@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"syscall"
 	"testing"
 )
 
@@ -17,6 +18,21 @@ import (
 
 // stubYtDlp writes an executable script that echoes the given stdout
 // and returns it as a provider config binary path.
+//
+// The write is held under syscall.ForkLock, and that is not tidiness:
+// the kernel refuses to exec a file that is open for writing anywhere
+// in the process, and these tests are parallel, so a *sibling* test's
+// fork can duplicate this descriptor in the moment it is open and
+// carry it past our close — the exec a moment later then fails with
+// ETXTBSY, "text file busy".  That is #146, seen once in CI and once
+// locally, on trees containing no Go at all.  Closing sooner is not
+// available (os.WriteFile has already closed the file before anything
+// execs it) and O_CLOEXEC does not help, because the window is between
+// another goroutine's fork and its own exec.  ForkLock is the lock
+// syscall.forkExec takes across that fork, so holding it here means no
+// child can exist while the descriptor does.  Measured on this helper
+// under 12 concurrent writers: 176-189 of 2400 execs refused without
+// it, 0 of 2400 with it.
 func stubYtDlp(t *testing.T, script string) string {
 	t.Helper()
 
@@ -26,9 +42,11 @@ func stubYtDlp(t *testing.T, script string) string {
 
 	path := filepath.Join(t.TempDir(), "yt-dlp")
 
-	if err := os.WriteFile(
-		path, []byte("#!/bin/sh\n"+script), 0o700,
-	); err != nil {
+	syscall.ForkLock.Lock()
+	err := os.WriteFile(path, []byte("#!/bin/sh\n"+script), 0o700)
+	syscall.ForkLock.Unlock()
+
+	if err != nil {
 		t.Fatalf("write stub: %v", err)
 	}
 

backend/explore/explore.go

@@ -2,6 +2,7 @@ package explore
 
 import (
 	"context"
+	"database/sql"
 	"log/slog"
 	"math"
 	"sort"
@@ -12,6 +13,7 @@ import (
 	"golang.org/x/sync/singleflight"
 
 	"yellowjacket/backend/database"
+	"yellowjacket/backend/database/sql/sqlcgen"
 	"yellowjacket/backend/events"
 	"yellowjacket/backend/jobs"
 )
@@ -279,37 +281,32 @@ func (e *Service) BackfillReleaseGroupMBIDs() {
 	go e.backfillReleaseGroupMBIDs(e.ctx)
 }
 
-func (e *Service) backfillReleaseGroupMBIDs(ctx context.Context) {
-	rows, err := e.db.QueryContext(
-		"SELECT id, pending_release_mbid FROM release_groups "+
-			"WHERE (mbid IS NULL OR mbid = '') "+
-			"AND pending_release_mbid IS NOT NULL AND pending_release_mbid != '' "+
-			"LIMIT ?",
-		releaseGroupMBIDBackfillMaxPerRun,
+// pendingReleaseMBIDs is the albums this pass has work to do on.
+//
+// It is separate from the pass, and returns its error rather than
+// logging it, so that a test can assert the statement runs against the
+// real schema. That is not a general preference -- it is this
+// statement's history: it named `release_groups`, a table plan 013
+// renamed to `albums`, so it failed on every launch since e7748f1 and
+// the pass returned quietly having done nothing. A test of the pass
+// as a whole cannot see that, because a query error and an empty
+// library are the same early return.
+func (e *Service) pendingReleaseMBIDs(
+	ctx context.Context,
+) ([]sqlcgen.GetAlbumsWithPendingReleaseMBIDRow, error) {
+	return e.db.ReadQueries.GetAlbumsWithPendingReleaseMBID(
+		ctx, releaseGroupMBIDBackfillMaxPerRun,
 	)
+}
+
+func (e *Service) backfillReleaseGroupMBIDs(ctx context.Context) {
+	pending, err := e.pendingReleaseMBIDs(ctx)
 	if err != nil {
 		e.logger.Warn("release-group mbid backfill: query failed", "error", err)
 
 		return
 	}
 
-	type pendingRow struct {
-		id          int64
-		releaseMBID string
-	}
-
-	var pending []pendingRow
-
-	for rows.Next() {
-		var p pendingRow
-
-		if err := rows.Scan(&p.id, &p.releaseMBID); err == nil {
-			pending = append(pending, p)
-		}
-	}
-
-	_ = rows.Close()
-
 	if len(pending) == 0 {
 		return
 	}
@@ -335,7 +332,7 @@ func (e *Service) backfillReleaseGroupMBIDs(ctx context.Context) {
 
 		job.progress(i, len(pending))
 
-		release, err := e.mb.LookupRelease(ctx, p.releaseMBID)
+		release, err := e.mb.LookupRelease(ctx, p.PendingReleaseMbid.String)
 		if err != nil || release.ReleaseGroupMBID == "" {
 			// Left alone rather than cleared: LookupRelease caches its
 			// answer (success or a release with no group) for 7 days,
@@ -344,12 +341,19 @@ func (e *Service) backfillReleaseGroupMBIDs(ctx context.Context) {
 			continue
 		}
 
-		_, err = e.db.ExecContext(
-			"UPDATE release_groups SET mbid = ?, pending_release_mbid = NULL "+
-				"WHERE id = ? AND (mbid IS NULL OR mbid = '')",
-			release.ReleaseGroupMBID, p.id,
-		)
-		if err != nil {
+		// The writer, not ReadQueries: an UPDATE issued on the
+		// query-only pool fails at runtime with "attempt to write a
+		// readonly database".
+		if err := e.db.Queries.ResolveAlbumPendingReleaseMBID(
+			ctx,
+			sqlcgen.ResolveAlbumPendingReleaseMBIDParams{
+				Mbid: sql.NullString{
+					String: release.ReleaseGroupMBID,
+					Valid:  true,
+				},
+				ID: p.ID,
+			},
+		); err != nil {
 			e.logger.Warn("release-group mbid backfill: update failed", "error", err)
 		}
 	}

backend/explore/pendingreleasembid_test.go

@@ -0,0 +1,250 @@
+package explore
+
+import (
+	"database/sql"
+	"log/slog"
+	"strconv"
+	"testing"
+
+	"yellowjacket/backend/database"
+	"yellowjacket/backend/database/sql/sqlcgen"
+)
+
+// The release-group MBID backfill queried `release_groups`, a table
+// plan 013 renamed to `albums`, so it failed on its first statement on
+// every launch from e7748f1 until #189 -- and the pass swallowed that,
+// because a query error and an empty library are the same early
+// return. Nothing noticed for two reasons worth keeping in mind:
+//
+//   - the statement was **raw SQL**, so sqlc never read it. Every other
+//     statement in the repo was renamed by the same change because sqlc
+//     reads sql/schemas/ and cannot generate against a table that is not
+//     declared. The two sqlc queries this now calls were written by 013
+//     and left uncalled.
+//   - it needs no network and no fixture library to reproduce. The
+//     failure is at prepare time.
+
+// seedPendingAlbum inserts an album whose files carried a release MBID
+// but no release-group MBID, which is what `library.updateMBIDs`
+// leaves behind for this pass to resolve.
+func seedPendingAlbum(
+	t *testing.T,
+	db *database.DB,
+	name, pendingMBID string,
+) int64 {
+	t.Helper()
+
+	res, err := db.ExecContext(
+		"INSERT INTO albums (name, artist_credit, pending_release_mbid) "+
+			"VALUES (?, ?, ?)",
+		name, "Test Artist", pendingMBID,
+	)
+	if err != nil {
+		t.Fatalf("insert albums row: %v", err)
+	}
+
+	id, err := res.LastInsertId()
+	if err != nil {
+		t.Fatalf("last insert id: %v", err)
+	}
+
+	return id
+}
+
+func newPendingTestService(db *database.DB) *Service {
+	return &Service{db: db, logger: slog.Default()}
+}
+
+// TestPendingReleaseMBIDsRunsAgainstTheRealSchema is the regression.
+//
+// It asserts the statement *runs*, which is the whole of what was
+// broken: against the old raw SQL this returns
+// "no such table: release_groups" rather than a row.
+func TestPendingReleaseMBIDsRunsAgainstTheRealSchema(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	e := newPendingTestService(db)
+
+	want := seedPendingAlbum(t, db, "Pending Album", "release-mbid-1")
+
+	pending, err := e.pendingReleaseMBIDs(db.Ctx)
+	if err != nil {
+		t.Fatalf("the backfill's query failed: %v", err)
+	}
+
+	if len(pending) != 1 {
+		t.Fatalf("got %d pending albums, want 1", len(pending))
+	}
+
+	if pending[0].ID != want {
+		t.Errorf("got album id %d, want %d", pending[0].ID, want)
+	}
+
+	if got := pending[0].PendingReleaseMbid.String; got != "release-mbid-1" {
+		t.Errorf("got pending mbid %q, want %q", got, "release-mbid-1")
+	}
+}
+
+// TestOnlyUnresolvedAlbumsAreReturned pins the two conditions that make
+// the pass idempotent, since between them they are what stops it doing
+// the same MusicBrainz lookups on every launch forever.
+func TestOnlyUnresolvedAlbumsAreReturned(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	e := newPendingTestService(db)
+
+	pendingID := seedPendingAlbum(t, db, "Still Pending", "release-mbid-1")
+
+	// Already resolved: it has a real MBID, so there is nothing to
+	// look up even though a marker is still sitting on it.
+	resolved := seedPendingAlbum(t, db, "Already Resolved", "release-mbid-2")
+	if err := db.Queries.SetAlbumMBID(db.Ctx, sqlcgen.SetAlbumMBIDParams{
+		Mbid: sql.NullString{String: "rg-mbid", Valid: true},
+		ID:   resolved,
+	}); err != nil {
+		t.Fatalf("set album mbid: %v", err)
+	}
+
+	// Never had a release MBID to resolve in the first place, which is
+	// most of a library.
+	seedPendingAlbum(t, db, "Nothing Pending", "")
+
+	pending, err := e.pendingReleaseMBIDs(db.Ctx)
+	if err != nil {
+		t.Fatalf("the backfill's query failed: %v", err)
+	}
+
+	if len(pending) != 1 || pending[0].ID != pendingID {
+		t.Fatalf(
+			"got %d albums %v, want only the unresolved one (%d)",
+			len(pending), pending, pendingID,
+		)
+	}
+}
+
+// TestResolvingClearsTheMarker is the other half: once the lookup has
+// answered, the album must stop being a candidate, or the pass repeats
+// the same live MusicBrainz call on every launch.
+func TestResolvingClearsTheMarker(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	e := newPendingTestService(db)
+
+	id := seedPendingAlbum(t, db, "Pending Album", "release-mbid-1")
+
+	// The writer, deliberately: this is an UPDATE, and the read pool
+	// would refuse it at runtime.
+	if err := db.Queries.ResolveAlbumPendingReleaseMBID(
+		db.Ctx,
+		sqlcgen.ResolveAlbumPendingReleaseMBIDParams{
+			Mbid: sql.NullString{String: "resolved-rg-mbid", Valid: true},
+			ID:   id,
+		},
+	); err != nil {
+		t.Fatalf("resolve pending release mbid: %v", err)
+	}
+
+	pending, err := e.pendingReleaseMBIDs(db.Ctx)
+	if err != nil {
+		t.Fatalf("the backfill's query failed: %v", err)
+	}
+
+	if len(pending) != 0 {
+		t.Fatalf("a resolved album is still a candidate: %v", pending)
+	}
+
+	album, err := db.ReadQueries.GetAlbum(db.Ctx, id)
+	if err != nil {
+		t.Fatalf("get album: %v", err)
+	}
+
+	if album.Mbid.String != "resolved-rg-mbid" {
+		t.Errorf("album mbid = %q, want the resolved one", album.Mbid.String)
+	}
+
+	if album.PendingReleaseMbid.Valid &&
+		album.PendingReleaseMbid.String != "" {
+		t.Errorf(
+			"the pending marker survived as %q",
+			album.PendingReleaseMbid.String,
+		)
+	}
+}
+
+// TestAResolvedMBIDIsNeverOverwritten covers the guard in the UPDATE.
+//
+// The pass runs against rows it read earlier, and a rescan can resolve
+// an album from its tags in between -- a real MBID from the file must
+// win over one this pass inferred from a release.
+func TestAResolvedMBIDIsNeverOverwritten(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+
+	id := seedPendingAlbum(t, db, "Pending Album", "release-mbid-1")
+
+	if err := db.Queries.SetAlbumMBID(db.Ctx, sqlcgen.SetAlbumMBIDParams{
+		Mbid: sql.NullString{String: "from-the-tags", Valid: true},
+		ID:   id,
+	}); err != nil {
+		t.Fatalf("set album mbid: %v", err)
+	}
+
+	if err := db.Queries.ResolveAlbumPendingReleaseMBID(
+		db.Ctx,
+		sqlcgen.ResolveAlbumPendingReleaseMBIDParams{
+			Mbid: sql.NullString{String: "from-the-backfill", Valid: true},
+			ID:   id,
+		},
+	); err != nil {
+		t.Fatalf("resolve pending release mbid: %v", err)
+	}
+
+	album, err := db.ReadQueries.GetAlbum(db.Ctx, id)
+	if err != nil {
+		t.Fatalf("get album: %v", err)
+	}
+
+	if album.Mbid.String != "from-the-tags" {
+		t.Errorf(
+			"album mbid = %q, want the tagged one to have won",
+			album.Mbid.String,
+		)
+	}
+}
+
+// TestThePassIsBounded checks the LIMIT.
+//
+// Each row costs a live MusicBrainz lookup on a 1 req/s limiter shared
+// with every page the user can open, so an unbounded read is a run that
+// lasts as long as the library is untagged. The sqlc query 013 wrote
+// had no LIMIT; the raw statement it was replacing did.
+func TestThePassIsBounded(t *testing.T) {
+	t.Parallel()
+
+	db := database.NewTestDB(t)
+	e := newPendingTestService(db)
+
+	for i := range releaseGroupMBIDBackfillMaxPerRun + 10 {
+		seedPendingAlbum(
+			t, db,
+			"Album "+string(rune('A'+i%26))+strconv.Itoa(i),
+			"release-mbid-"+strconv.Itoa(i),
+		)
+	}
+
+	pending, err := e.pendingReleaseMBIDs(db.Ctx)
+	if err != nil {
+		t.Fatalf("the backfill's query failed: %v", err)
+	}
+
+	if len(pending) != releaseGroupMBIDBackfillMaxPerRun {
+		t.Errorf(
+			"got %d albums, want the run bounded at %d",
+			len(pending), releaseGroupMBIDBackfillMaxPerRun,
+		)
+	}
+}

backend/library/rescan.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"yellowjacket/backend/coverart"
+	"yellowjacket/backend/database"
 )
 
 var errNoLibrariesConfigured = errors.New(
@@ -137,34 +138,12 @@ func (l *Library) clearLibraryTables() error {
 	// metadata for all linked tracks before audio_files are deleted.
 	// ON DELETE SET NULL will null out audio_file_id, converting them
 	// to phantoms that ResolvePhantomTracksAfterScan can re-link.
-	if _, err := tx.ExecContext(l.ctx, `
-		UPDATE playlist_tracks
-		SET
-			phantom_title = COALESCE(phantom_title, (
-				SELECT tm.title FROM track_metadata tm
-				WHERE tm.id = playlist_tracks.audio_file_id
-			)),
-			phantom_artist = COALESCE(phantom_artist, (
-				SELECT tm.artist_name FROM track_metadata tm
-				WHERE tm.id = playlist_tracks.audio_file_id
-			)),
-			phantom_album = COALESCE(phantom_album, (
-				SELECT tm.album FROM track_metadata tm
-				WHERE tm.id = playlist_tracks.audio_file_id
-			)),
-			phantom_duration_ms = COALESCE(phantom_duration_ms, (
-				SELECT af.length_milliseconds FROM audio_files af
-				WHERE af.id = playlist_tracks.audio_file_id
-			)),
-			phantom_file_path = COALESCE(phantom_file_path, (
-				SELECT af.file_path FROM audio_files af
-				WHERE af.id = playlist_tracks.audio_file_id
-			))
-		WHERE audio_file_id IS NOT NULL
-	`); err != nil {
-		return fmt.Errorf(
-			"could not preserve playlist track metadata: %w", err,
-		)
+	//
+	// Shared with the stale-shape retire in backend/database, which is
+	// the other path that empties this table and which did not do this
+	// (#183): the statement lives there so the two cannot drift again.
+	if err := database.PreservePlaylistPhantoms(l.ctx, tx, l.logger); err != nil {
+		return err
 	}
 
 	// Phase 2: the files.  file_genres cascades with them.

backend/metadata/tags.go

@@ -74,6 +74,14 @@ func ExtractTags(path string) (*TrackMetadata, error) {
 
 // ExtractTagsFromReader reads metadata from an io.ReadSeeker.
 func ExtractTagsFromReader(r io.ReadSeeker) (*TrackMetadata, error) {
+	// The container decides, so this is asked before tag.ReadFrom and
+	// not after its failure: a WAV's tags live in a RIFF chunk that
+	// dhowden/tag cannot see, and its fallback -- an ID3v1 trailer --
+	// would otherwise outrank them.
+	if meta, ok := wavTags(r); ok {
+		return meta, nil
+	}
+
 	m, err := tag.ReadFrom(r)
 	if err != nil {
 		// No tags found is not necessarily an error - return empty metadata

backend/metadata/tags_wav.go

@@ -0,0 +1,68 @@
+package metadata
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+
+	"yellowjacket/backend/riff"
+)
+
+// wavTags reads the ID3v2 tag a WAV carries in its RIFF "id3 " chunk,
+// which is where backend/tagwriter puts it and where dhowden/tag --
+// having no RIFF reader at all -- cannot look.  Without this a WAV
+// scans as an untagged file however carefully it was tagged.
+//
+// ok is false when r is not a RIFF/WAVE container, and the read
+// position is restored either way so the caller can carry on.
+func wavTags(r io.ReadSeeker) (*TrackMetadata, bool) {
+	start, err := r.Seek(0, io.SeekCurrent)
+	if err != nil {
+		return nil, false
+	}
+
+	id3Data, chunkErr := riff.ID3Chunk(r)
+
+	if _, err := r.Seek(start, io.SeekStart); err != nil {
+		return nil, false
+	}
+
+	switch {
+	case chunkErr == nil:
+		return wavTagsFrom(id3Data), true
+
+	// Not ours to read: let the ordinary dispatch have the file.
+	case errors.Is(chunkErr, riff.ErrNotRIFF), errors.Is(chunkErr, riff.ErrNotWAVE):
+		return nil, false
+
+	// A RIFF container we cannot get a tag out of -- no chunk, an RF64
+	// file, a truncated header.  That is a file with no readable tags,
+	// which is what the scanner's filename fallback is for.
+	default:
+		return &TrackMetadata{}, true
+	}
+}
+
+// wavTagsFrom parses the bytes of a WAV's ID3v2 chunk.
+func wavTagsFrom(id3Data []byte) *TrackMetadata {
+	meta, err := extractID3v2Lenient(bytes.NewReader(id3Data))
+	if err != nil {
+		// A tag holding no frames is not a damaged tag: writing every
+		// field back out empty leaves one, and warning about it would
+		// put a fault on a file that has none.
+		if errors.Is(err, ErrTagsUnreadable) {
+			return &TrackMetadata{}
+		}
+
+		return &TrackMetadata{
+			TagReadWarning: fmt.Errorf("%w: %w", ErrTagsUnreadable, err),
+		}
+	}
+
+	// extractID3v2Lenient names MP3, being the recovery path for one.
+	meta.FileFormat = strings.ToUpper(strings.TrimPrefix(string(WAV), "."))
+
+	return meta
+}

backend/player/buffered_streamer.go

@@ -47,6 +47,39 @@ type BufferedStreamer struct {
 	// seek bar and suppresses its interpolation.
 	starved      int
 	starvedSince time.Time
+
+	// underruns accumulates for the life of this streamer, where
+	// starved is reset by every arriving sample.
+	//
+	// The two answer different questions and only the first was being
+	// asked. starved is a *stall* detector: it exists to end a track
+	// whose source has died, so it forgets a run the moment audio
+	// resumes -- which is exactly the case this counts. A hundred 20ms
+	// underruns a minute never approach the give-up threshold and were
+	// invisible to the log, the UI and every test tier, while being
+	// audible as static: an underrun is served as a run of zeros
+	// spliced into the waveform, and a step discontinuity at each edge
+	// is what a click is.
+	underruns UnderrunStats
+}
+
+// UnderrunStats is what the ring buffer missed, cumulatively.
+//
+// Samples rather than milliseconds because this type does not know the
+// sample rate -- the player does, and converts at the point of
+// reporting.
+type UnderrunStats struct {
+	// Runs is the number of *episodes*: transitions from healthy into
+	// starved. Calls is how many Stream calls were served with
+	// silence, and Samples is how much silence that was.
+	//
+	// Runs is the count that means something audible. One episode is
+	// one pop however many calls it spans, and the ratio of the two is
+	// how long the average episode was -- which is what separates
+	// "clicking" from "dropping out".
+	Runs    int64
+	Calls   int64
+	Samples int64
 }
 
 // The silence fill is bounded by both a duration and a run of calls,
@@ -226,6 +259,13 @@ func (bs *BufferedStreamer) Stream(
 		// but only for a bounded stretch, because "forever" is
 		// reported upward as healthy playback and there is no watchdog
 		// above this to notice otherwise.
+		if bs.starved == 0 {
+			bs.underruns.Runs++
+		}
+
+		bs.underruns.Calls++
+		bs.underruns.Samples += int64(len(samples))
+
 		bs.starved++
 
 		if bs.starvedSince.IsZero() {
@@ -269,6 +309,20 @@ func (bs *BufferedStreamer) Stream(
 	return n, true
 }
 
+// Underruns returns the cumulative underrun count.
+//
+// It is a snapshot rather than a live view, and it is read from
+// outside the audio callback: counting happens in Stream, under the
+// lock it already takes, because that path has a real-time deadline
+// and anything that allocates or formats on it is a cause of the
+// defect it is measuring rather than a measurement of it.
+func (bs *BufferedStreamer) Underruns() UnderrunStats {
+	bs.mu.Lock()
+	defer bs.mu.Unlock()
+
+	return bs.underruns
+}
+
 // Err returns any error encountered by the source streamer.
 func (bs *BufferedStreamer) Err() error {
 	bs.mu.Lock()
@@ -298,6 +352,10 @@ func (bs *BufferedStreamer) Flush() {
 
 // resetStarvationLocked forgets an underrun run.  Must be called with
 // bs.mu held.
+//
+// Deliberately does not touch bs.underruns: forgetting the run is what
+// makes starved a stall detector, and remembering it is the whole
+// point of the counter beside it.
 func (bs *BufferedStreamer) resetStarvationLocked() {
 	bs.starved = 0
 	bs.starvedSince = time.Time{}

backend/player/buffered_underrun_test.go

@@ -0,0 +1,279 @@
+package player
+
+import (
+	"sync"
+	"testing"
+	"time"
+)
+
+// An underrun is audible and nothing counted it (#135).
+//
+// The distinction these tests exist for is that `starved` and
+// `underruns` disagree on purpose. `starved` is a stall detector: it is
+// reset by every arriving sample, because its job is to end a track
+// whose source has died and a source that is merely slow must not be
+// cut short (TestUnderrunsDoNotAccumulateAcrossASlowSource, next
+// door). That reset is exactly what made the audible case invisible --
+// a hundred short underruns a minute never approach the give-up
+// threshold, and each one is a run of zeros spliced into the waveform
+// with a step discontinuity at both edges.
+
+// TestAnEmptyRingIsCounted is the measurement itself: silence served
+// for a missing sample is recorded rather than merely tolerated.
+func TestAnEmptyRingIsCounted(t *testing.T) {
+	t.Parallel()
+
+	// A source that never produces is the cleanest way to make the
+	// ring empty on demand; the stall budget is far longer than the
+	// handful of calls below.
+	bs := NewBufferedStreamer(stalledStreamer{}, 1024)
+	defer bs.Close()
+
+	if got := bs.Underruns(); got != (UnderrunStats{}) {
+		t.Fatalf("a fresh streamer already reports %+v", got)
+	}
+
+	buf := make([][2]float64, 256)
+
+	for range 3 {
+		if _, ok := bs.Stream(buf); !ok {
+			t.Fatal("the stall budget ran out before the test did")
+		}
+	}
+
+	got := bs.Underruns()
+
+	if got.Calls != 3 {
+		t.Errorf("Calls = %d, want 3", got.Calls)
+	}
+
+	if got.Samples != int64(3*len(buf)) {
+		t.Errorf("Samples = %d, want %d", got.Samples, 3*len(buf))
+	}
+
+	// Three consecutive silent calls are one episode, not three. That
+	// is the number that means something audible: one interruption is
+	// one pop however many callbacks it spans.
+	if got.Runs != 1 {
+		t.Errorf("Runs = %d, want 1 -- an unbroken run is one episode", got.Runs)
+	}
+}
+
+// TestSilenceIsWhatIsCounted pins what an underrun actually does to the
+// waveform, which is the reason to count it at all.
+func TestSilenceIsWhatIsCounted(t *testing.T) {
+	t.Parallel()
+
+	bs := NewBufferedStreamer(stalledStreamer{}, 1024)
+	defer bs.Close()
+
+	buf := make([][2]float64, 64)
+	for i := range buf {
+		buf[i] = [2]float64{0.5, 0.5}
+	}
+
+	n, ok := bs.Stream(buf)
+	if !ok || n != len(buf) {
+		t.Fatalf("Stream = (%d, %v), want (%d, true)", n, ok, len(buf))
+	}
+
+	for i := range buf {
+		if buf[i] != ([2]float64{}) {
+			t.Fatalf("sample %d is %v, want silence", i, buf[i])
+		}
+	}
+
+	if got := bs.Underruns().Samples; got != int64(len(buf)) {
+		t.Errorf("counted %d samples of silence, wrote %d", got, len(buf))
+	}
+}
+
+// TestSeparateEpisodesAreSeparateRuns is the counter's whole shape:
+// audio arriving between two underruns makes them two, because that is
+// two interruptions and two clicks.
+func TestSeparateEpisodesAreSeparateRuns(t *testing.T) {
+	t.Parallel()
+
+	// A source that yields nothing until it is fed, so the ring can be
+	// emptied, filled and emptied again on demand.
+	src := &gatedStreamer{}
+
+	bs := NewBufferedStreamer(src, 1024)
+	defer bs.Close()
+
+	buf := make([][2]float64, 128)
+
+	starve := func() {
+		t.Helper()
+
+		for range 2 {
+			if _, ok := bs.Stream(buf); !ok {
+				t.Fatal("the stall budget ran out before the test did")
+			}
+		}
+	}
+
+	// feed lets exactly one bufferful through and drains it, so the
+	// ring is empty again on return. Allowing more would mean the
+	// starve() after it drained real audio instead of underrunning,
+	// which is what the first version of this test did -- it reported
+	// one episode and looked like the counter was wrong.
+	feed := func() {
+		t.Helper()
+
+		src.allow(len(buf))
+
+		// The read-ahead is a goroutine, so wait for real samples
+		// rather than assuming they have landed.
+		deadline := time.Now().Add(2 * time.Second)
+		for time.Now().Before(deadline) {
+			n, ok := bs.Stream(buf)
+			if ok && n > 0 && buf[0] != ([2]float64{}) {
+				return
+			}
+
+			time.Sleep(time.Millisecond)
+		}
+
+		t.Fatal("the source never delivered a sample")
+	}
+
+	starve()
+	feed()
+	starve()
+
+	if got := bs.Underruns().Runs; got < 2 {
+		t.Errorf(
+			"Runs = %d, want at least 2 -- audio in between makes two "+
+				"episodes, not one",
+			got,
+		)
+	}
+}
+
+// TestTheStallResetDoesNotClearTheCounter is the regression this file
+// is really about.
+//
+// resetStarvationLocked runs on every arriving sample and on every
+// Flush. If it cleared the cumulative count too, the counter would
+// report zero on exactly the workload it exists to measure -- a stream
+// that underruns repeatedly but always recovers -- which is
+// indistinguishable from healthy playback and is what the code did
+// before #135.
+func TestTheStallResetDoesNotClearTheCounter(t *testing.T) {
+	t.Parallel()
+
+	bs := NewBufferedStreamer(stalledStreamer{}, 1024)
+	defer bs.Close()
+
+	buf := make([][2]float64, 128)
+
+	if _, ok := bs.Stream(buf); !ok {
+		t.Fatal("the stall budget ran out before the test did")
+	}
+
+	before := bs.Underruns()
+	if before.Runs == 0 {
+		t.Fatal("nothing was counted, so the reset cannot be tested")
+	}
+
+	// Both of the ways a run is forgotten.
+	bs.mu.Lock()
+	bs.resetStarvationLocked()
+	bs.mu.Unlock()
+
+	bs.Flush()
+
+	if got := bs.Underruns(); got != before {
+		t.Errorf(
+			"forgetting the stall run also discarded the count: %+v, "+
+				"want %+v",
+			got, before,
+		)
+	}
+}
+
+// TestUnderrunDeltaNeverGoesBackwards covers the one arithmetic trap in
+// the reporting side.
+//
+// The counter belongs to the streamer and the streamer is replaced on
+// every track, so a baseline carried across a track change is the
+// previous track's total subtracted from a fresh zero. The load path
+// resets the baseline, and this clamps as well -- a negative count in a
+// log line reads as a broken instrument, which would discredit the
+// measurement rather than merely mis-state it.
+func TestUnderrunDeltaNeverGoesBackwards(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		now  UnderrunStats
+		last UnderrunStats
+		want UnderrunStats
+	}{
+		{
+			name: "ordinary progress",
+			now:  UnderrunStats{Runs: 5, Calls: 40, Samples: 4000},
+			last: UnderrunStats{Runs: 2, Calls: 10, Samples: 1000},
+			want: UnderrunStats{Runs: 3, Calls: 30, Samples: 3000},
+		},
+		{
+			name: "nothing happened",
+			now:  UnderrunStats{Runs: 5, Calls: 40, Samples: 4000},
+			last: UnderrunStats{Runs: 5, Calls: 40, Samples: 4000},
+			want: UnderrunStats{},
+		},
+		{
+			name: "a new streamer, with a stale baseline",
+			now:  UnderrunStats{},
+			last: UnderrunStats{Runs: 9, Calls: 90, Samples: 9000},
+			want: UnderrunStats{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := underrunDelta(tt.now, tt.last); got != tt.want {
+				t.Errorf("underrunDelta = %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+// gatedStreamer produces only what it has been allowed to, and
+// otherwise stalls without ending -- so a test can decide exactly when
+// the ring runs dry.
+type gatedStreamer struct {
+	mu        sync.Mutex
+	remaining int
+}
+
+func (g *gatedStreamer) allow(n int) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	g.remaining += n
+}
+
+func (g *gatedStreamer) Stream(samples [][2]float64) (int, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	if g.remaining <= 0 {
+		return 0, true
+	}
+
+	n := min(len(samples), g.remaining)
+
+	for i := range n {
+		samples[i] = [2]float64{0.25, 0.25}
+	}
+
+	g.remaining -= n
+
+	return n, true
+}
+
+func (g *gatedStreamer) Err() error { return nil }

backend/player/player.go

@@ -39,16 +39,21 @@ type Player struct {
 	// via the queue).
 	mu sync.Mutex
 
-	ctx                     context.Context
-	logger                  *slog.Logger
-	db                      *database.DB
-	state                   State
-	currentFile             *os.File
-	format                  beep.Format
-	baseStreamer            beep.Streamer
-	seeker                  beep.StreamSeeker
-	resampled               beep.Streamer
-	buffered                *BufferedStreamer
+	ctx          context.Context
+	logger       *slog.Logger
+	db           *database.DB
+	state        State
+	currentFile  *os.File
+	format       beep.Format
+	baseStreamer beep.Streamer
+	seeker       beep.StreamSeeker
+	resampled    beep.Streamer
+	buffered     *BufferedStreamer
+
+	// lastUnderruns is the previous report, so the 1 Hz log can say
+	// what happened in the last second and stay quiet when nothing did.
+	// It is reset with the streamer, in loadFileLocked.
+	lastUnderruns           UnderrunStats
 	control                 *beep.Ctrl
 	volume                  *effects.Volume
 	speakerStreamer         beep.Streamer
@@ -71,6 +76,19 @@ type Player struct {
 	// not something the user chose.
 	duckAmount float64
 
+	// systemVolume is what SystemOwnsVolume answers: the platform's own
+	// control is the only one, so ours neither acts nor persists.  It is
+	// a field rather than the build constant read directly so that a
+	// test can exercise both sides on any machine.  See systemvolume.go.
+	systemVolume bool
+
+	// storedVolume and storedMuted hold the persisted level as it was
+	// found at restore, for a platform whose volume we do not own: the
+	// maximum we then run at is not a level the user chose, so saveState
+	// writes back what it read rather than overwriting it.
+	storedVolume UserVolume
+	storedMuted  bool
+
 	// trackLengthMs holds the authoritative track duration in
 	// milliseconds, sourced from the database (which uses the
 	// custom header parser).  The go-mp3 decoder's Len() can be
@@ -156,6 +174,8 @@ func NewPlayer(logger *slog.Logger, db *database.DB) *Player {
 		logger:       logger,
 		db:           db,
 		state:        Stopped,
+		systemVolume: platformOwnsVolume,
+		storedVolume: DefaultUserVol,
 		baseStreamer: generators.Silence(-1),
 		format: beep.Format{
 			SampleRate: speakerSampleRate,
@@ -277,9 +297,78 @@ func (p *Player) emitPositionIfPlaying() {
 		return
 	}
 
+	p.reportUnderrunsLocked()
 	p.emitPositionLocked()
 }
 
+// underrunDelta is what happened since the last report.
+//
+// It clamps at zero rather than subtracting blind, because the counter
+// belongs to the *streamer* and the streamer is replaced on every
+// track: a baseline carried across that boundary is the previous
+// track's total subtracted from a fresh zero, which is negative. That
+// is repaired at the load (lastUnderruns is reset with the streamer)
+// and clamped here as well, because a negative count in a log line
+// reads as a broken instrument and would discredit the measurement
+// this exists to make.
+func underrunDelta(now, last UnderrunStats) UnderrunStats {
+	return UnderrunStats{
+		Runs:    max(0, now.Runs-last.Runs),
+		Calls:   max(0, now.Calls-last.Calls),
+		Samples: max(0, now.Samples-last.Samples),
+	}
+}
+
+// reportUnderrunsLocked logs what the ring buffer missed, at most once
+// a second and only when the number moved.  Must be called with p.mu
+// held.
+//
+// **An underrun is audible and nothing counted it** (#135). The ring
+// serves silence when it is empty, so a run of zeros is spliced into
+// the waveform and the step discontinuity at each edge is a click; a
+// series of short ones is static. Everything that makes one likelier
+// is worse on a phone than on a desktop -- slower storage, a governor
+// that parks cores, background work, GC -- and no tier here can see it,
+// since CI's audio device is a null sink chosen because it keeps time.
+//
+// Three things about the reporting are deliberate.
+//
+// **It is on the 1 Hz position ticker rather than in Stream.** Stream
+// runs on the speaker callback's real-time deadline, and a log line
+// there would allocate, format and write on the exact path whose
+// missed deadline is the defect -- measuring by making it worse.
+//
+// **An unchanged count is not logged.** That is emitStatus' rule one
+// package over: a healthy player is silent, so anything in the log is
+// news, and the line appears exactly while it is popping. Reading it
+// off a device means `make android-logs` with the audio audible.
+//
+// **It is Info rather than Debug**, because the default level is Info
+// and a phone has no convenient way to set YJ_LOG_LEVEL -- a debug
+// line here would be a counter nobody on the affected platform can
+// read, which is the shape of the bug that made #160 necessary.
+func (p *Player) reportUnderrunsLocked() {
+	if p.buffered == nil {
+		return
+	}
+
+	stats := p.buffered.Underruns()
+	if stats == p.lastUnderruns {
+		return
+	}
+
+	since := underrunDelta(stats, p.lastUnderruns)
+	p.lastUnderruns = stats
+
+	slog.Info("audio underrun",
+		"runs", since.Runs,
+		"calls", since.Calls,
+		"silenceMs", speakerSampleRate.D(int(since.Samples)).Milliseconds(),
+		"trackRuns", stats.Runs,
+		"trackSilenceMs", speakerSampleRate.D(int(stats.Samples)).Milliseconds(),
+	)
+}
+
 // emitPositionLocked pushes the current position to the frontend.
 // Must be called with p.mu held.
 func (p *Player) emitPositionLocked() {
@@ -469,6 +558,12 @@ func (p *Player) updateStreamers(
 		p.resampled, int(speakerSampleRate)*2,
 	)
 
+	// The counter belongs to the streamer, so the baseline it is
+	// reported against has to go with it -- otherwise the first report
+	// of a new track is the previous track's total subtracted from
+	// zero, which is negative and looks like the instrument is broken.
+	p.lastUnderruns = UnderrunStats{}
+
 	// wrap in ctrl streamer to allow play/pause
 	p.control = &beep.Ctrl{Streamer: p.buffered}
 
@@ -875,6 +970,10 @@ func (p *Player) SetVolume(desiredVolume UserVolume) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
+	if p.systemVolume {
+		return
+	}
+
 	p.setVolumeLocked(desiredVolume)
 	p.emitVolumeChanged()
 	p.saveState()
@@ -923,6 +1022,10 @@ func (p *Player) ChangeVolume(deltaVolume int) error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
+	if p.systemVolume {
+		return nil
+	}
+
 	p.setVolumeLocked(p.getUserVolume() + UserVolume(deltaVolume))
 	p.emitVolumeChanged()
 	p.saveState()
@@ -953,6 +1056,14 @@ func (p *Player) MuteToggle() error {
 		return errNoAudioFileLoaded
 	}
 
+	// Mute is a level of zero by another name, so it goes with the rest
+	// of the volume where the system owns it -- and it would be the one
+	// state on such a platform the user could not get out of, since with
+	// no control rendered there is nothing left to un-mute with.
+	if p.systemVolume {
+		return nil
+	}
+
 	speaker.Lock()
 	p.volume.Silent = !p.volume.Silent
 	speaker.Unlock()
@@ -1403,7 +1514,15 @@ func (p *Player) saveState() {
 	volume := int64(DefaultUserVol)
 	muted := false
 
-	if p.volume != nil {
+	switch {
+	case p.systemVolume:
+		// The maximum this platform runs at is not a level anybody
+		// chose, so it is not one to remember.  Writing back what
+		// restore found keeps the row a description of the user's
+		// setting without needing a second query that omits the column.
+		volume = int64(p.storedVolume)
+		muted = p.storedMuted
+	case p.volume != nil:
 		volume = int64(p.getUserVolume())
 		muted = p.volume.Silent
 	}
@@ -1487,11 +1606,20 @@ func (p *Player) restoreStateLocked() {
 		}
 	}
 
-	vol := clampVolume(UserVolume(state.Volume))
-	p.setVolumeLocked(vol)
+	if p.systemVolume {
+		// Remembered, not applied: the device's keys are the volume
+		// control here, so the player runs wide open and hands the
+		// stored level back untouched at the next save.
+		p.storedVolume = clampVolume(UserVolume(state.Volume))
+		p.storedMuted = state.Muted
+		p.setVolumeLocked(MaxUserVol)
+	} else {
+		vol := clampVolume(UserVolume(state.Volume))
+		p.setVolumeLocked(vol)
 
-	if state.Muted {
-		p.volume.Silent = true
+		if state.Muted {
+			p.volume.Silent = true
+		}
 	}
 
 	// Restore last track if the file still exists.
@@ -1531,8 +1659,9 @@ func (p *Player) restoreStateLocked() {
 	}
 
 	p.logger.Info("Player state restored",
-		"volume", vol,
-		"muted", state.Muted,
+		"volume", p.getUserVolume(),
+		"muted", p.volume.Silent,
+		"systemVolume", p.systemVolume,
 		"trackPath", state.LastTrackPath,
 		"positionSeconds", state.LastPositionSeconds,
 	)

backend/player/systemvolume.go

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

backend/player/systemvolume_android.go

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

backend/player/systemvolume_other.go

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

backend/player/systemvolume_test.go

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

backend/queue/playhistory.go

@@ -6,7 +6,7 @@ import (
 	"yellowjacket/backend/events"
 )
 
-// recordPlay inserts a play_history row and updates the denormalized
+// recordPlay inserts a listening_events row and updates the denormalized
 // play_count / last_played columns on audio_files. Called from
 // OnPlaybackFinished for the track that just finished.
 //
@@ -20,10 +20,12 @@ func (q *Queue) recordPlay(audioFileID int64) {
 
 	now := time.Now().UTC().Format(time.DateTime)
 
-	// Insert play_history row.
+	// Insert the listening event.  A natural finish is a 'complete' by
+	// construction; position/duration are the classifier's to fill once
+	// skips are recorded (see .planning/plans/active/021).
 	_, err := q.db.ExecContext(
-		`INSERT INTO play_history (audio_file_id, played_at)
-		 VALUES (?, ?)`,
+		`INSERT INTO listening_events (audio_file_id, kind, occurred_at)
+		 VALUES (?, 'complete', ?)`,
 		audioFileID, now,
 	)
 	if err != nil {

backend/riff/riff.go

@@ -0,0 +1,186 @@
+// Package riff reads the chunk layout of a RIFF/WAVE container.
+//
+// It exists because both halves of WAV tagging need it and neither can
+// import the other: backend/tagwriter writes a WAV's tags into a RIFF
+// "id3 " chunk and already imports backend/metadata, which is what has
+// to read them back out.  backend/tagtotals is the precedent.
+//
+// The two readers here are deliberately different.  Parse holds every
+// chunk's data in memory, which is what rewriting a file needs; a WAV's
+// audio *is* the "data" chunk, so doing that on the scan path would
+// read every library file in full.  ID3Chunk seeks over what it is not
+// looking for instead.  Both walk the same headers.
+package riff
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// Sentinel errors describing a container this package will not read.
+var (
+	ErrRF64NotSupported = errors.New("RF64 files are not yet supported")
+	ErrNotRIFF          = errors.New("not a RIFF file")
+	ErrNotWAVE          = errors.New("not a WAVE file")
+	ErrNoID3Chunk       = errors.New("no ID3 chunk in RIFF file")
+)
+
+// Chunk holds a single RIFF sub-chunk (ID + raw data).
+type Chunk struct {
+	ID   [4]byte
+	Data []byte
+}
+
+// IsID3 reports whether id is that of an ID3v2 RIFF chunk.  Both
+// lowercase "id3 " and uppercase "ID3 " are accepted.
+func IsID3(id [4]byte) bool {
+	return strings.ToLower(string(id[:3])) == "id3"
+}
+
+// Parse reads every RIFF sub-chunk from r, in order, starting at the
+// reader's current position.  It rejects RF64 files and non-WAVE
+// containers with descriptive errors.  The parser is lenient: it
+// tolerates a missing final padding byte and ignores the declared
+// RIFF size.
+func Parse(r io.Reader) ([]Chunk, error) {
+	if err := readContainer(r); err != nil {
+		return nil, err
+	}
+
+	var chunks []Chunk
+
+	for {
+		id, size, err := nextHeader(r)
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return nil, err
+		}
+
+		// Copied rather than allocated up front, as ID3Chunk does: the
+		// size is four bytes off the file, so a truncated one is free to
+		// declare a chunk larger than the whole of itself.
+		var data bytes.Buffer
+		if _, err := io.CopyN(&data, r, int64(size)); err != nil {
+			return nil, fmt.Errorf("read chunk data for %q: %w", id, err)
+		}
+
+		chunks = append(chunks, Chunk{ID: id, Data: data.Bytes()})
+
+		// Odd-length chunks have a padding byte.  Lenient: if the
+		// read fails (e.g. EOF), just break rather than error.
+		if size%2 != 0 {
+			var pad [1]byte
+
+			if _, err := r.Read(pad[:]); err != nil {
+				break
+			}
+		}
+	}
+
+	return chunks, nil
+}
+
+// ID3Chunk returns the payload of the ID3v2 chunk of the RIFF/WAVE
+// container at the reader's current position, seeking over every other
+// chunk rather than reading it.  It returns ErrNoID3Chunk when the
+// container carries no such chunk, and leaves the read position
+// unspecified either way.
+func ID3Chunk(r io.ReadSeeker) ([]byte, error) {
+	if err := readContainer(r); err != nil {
+		return nil, err
+	}
+
+	for {
+		id, size, err := nextHeader(r)
+		if errors.Is(err, io.EOF) {
+			return nil, ErrNoID3Chunk
+		}
+
+		if err != nil {
+			return nil, err
+		}
+
+		if !IsID3(id) {
+			// Odd-length chunks carry a padding byte.  Seeking past
+			// the end of the file is not an error; the next header
+			// read is what reports the end.
+			if _, err := r.Seek(int64(size)+int64(size%2), io.SeekCurrent); err != nil {
+				return nil, fmt.Errorf("skip chunk %q: %w", id, err)
+			}
+
+			continue
+		}
+
+		// Copied rather than allocated up front: a truncated file is
+		// free to declare a chunk larger than the whole of itself.
+		var data bytes.Buffer
+		if _, err := io.CopyN(&data, r, int64(size)); err != nil {
+			return nil, fmt.Errorf("read chunk data for %q: %w", id, err)
+		}
+
+		return data.Bytes(), nil
+	}
+}
+
+// readContainer consumes the 12-byte RIFF/WAVE header at the reader's
+// current position.
+func readContainer(r io.Reader) error {
+	var magic [4]byte
+	if _, err := io.ReadFull(r, magic[:]); err != nil {
+		return fmt.Errorf("read RIFF magic: %w", err)
+	}
+
+	if string(magic[:]) == "RF64" {
+		return ErrRF64NotSupported
+	}
+
+	if string(magic[:]) != "RIFF" {
+		return fmt.Errorf("%w: got %q", ErrNotRIFF, magic)
+	}
+
+	// Read (and discard) RIFF size — lenient, do not enforce.
+	var riffSize uint32
+	if err := binary.Read(r, binary.LittleEndian, &riffSize); err != nil {
+		return fmt.Errorf("read RIFF size: %w", err)
+	}
+
+	var form [4]byte
+	if _, err := io.ReadFull(r, form[:]); err != nil {
+		return fmt.Errorf("read WAVE form type: %w", err)
+	}
+
+	if string(form[:]) != "WAVE" {
+		return fmt.Errorf("%w: got %q", ErrNotWAVE, form)
+	}
+
+	return nil
+}
+
+// nextHeader reads one sub-chunk header.  It returns io.EOF once the
+// chunks are exhausted, including for a header cut short.
+func nextHeader(r io.Reader) ([4]byte, uint32, error) {
+	var id [4]byte
+
+	_, err := io.ReadFull(r, id[:])
+	if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
+		return id, 0, io.EOF
+	}
+
+	if err != nil {
+		return id, 0, fmt.Errorf("read chunk ID: %w", err)
+	}
+
+	var size uint32
+	if err := binary.Read(r, binary.LittleEndian, &size); err != nil {
+		return id, 0, fmt.Errorf("read chunk size for %q: %w", id, err)
+	}
+
+	return id, size, nil
+}

backend/riff/riff_test.go

@@ -0,0 +1,254 @@
+package riff_test
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"runtime"
+	"testing"
+
+	"yellowjacket/backend/riff"
+)
+
+// chunk is one sub-chunk to put in a test container.
+type chunk struct {
+	id   string
+	data []byte
+}
+
+// buildRIFF assembles a container from magic, form type and chunks,
+// padding odd-length chunks the way a writer must.
+func buildRIFF(magic, form string, chunks []chunk) []byte {
+	var body bytes.Buffer
+
+	body.WriteString(form)
+
+	for _, c := range chunks {
+		body.WriteString(c.id)
+		_ = binary.Write(&body, binary.LittleEndian, uint32(len(c.data)))
+		body.Write(c.data)
+
+		if len(c.data)%2 != 0 {
+			body.WriteByte(0)
+		}
+	}
+
+	var out bytes.Buffer
+
+	out.WriteString(magic)
+	_ = binary.Write(&out, binary.LittleEndian, uint32(body.Len()))
+	out.Write(body.Bytes())
+
+	return out.Bytes()
+}
+
+func TestID3Chunk_FindsTheTagPastTheAudio(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		chunks []chunk
+		want   string
+	}{
+		{
+			name: "after an odd-length chunk",
+			chunks: []chunk{
+				{id: "fmt ", data: make([]byte, 16)},
+				{id: "LIST", data: []byte("INFOodd")},
+				{id: "data", data: make([]byte, 200)},
+				{id: "id3 ", data: []byte("ID3vTAG")},
+			},
+			want: "ID3vTAG",
+		},
+		{
+			// The chunk ID is written both ways in the wild, and the
+			// writer accepts either, so the reader must too.
+			name: "uppercase ID3",
+			chunks: []chunk{
+				{id: "data", data: make([]byte, 8)},
+				{id: "ID3 ", data: []byte("upper")},
+			},
+			want: "upper",
+		},
+		{
+			name: "first chunk",
+			chunks: []chunk{
+				{id: "id3 ", data: []byte("first")},
+				{id: "data", data: make([]byte, 8)},
+			},
+			want: "first",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			r := bytes.NewReader(buildRIFF("RIFF", "WAVE", tc.chunks))
+
+			got, err := riff.ID3Chunk(r)
+			if err != nil {
+				t.Fatalf("ID3Chunk: %v", err)
+			}
+
+			if string(got) != tc.want {
+				t.Errorf("chunk data: got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestID3Chunk_RejectsWhatItCannotRead(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		bytes []byte
+		want  error
+	}{
+		{
+			name:  "no ID3 chunk",
+			bytes: buildRIFF("RIFF", "WAVE", []chunk{{id: "data", data: []byte{1, 2}}}),
+			want:  riff.ErrNoID3Chunk,
+		},
+		{
+			name:  "no chunks at all",
+			bytes: buildRIFF("RIFF", "WAVE", nil),
+			want:  riff.ErrNoID3Chunk,
+		},
+		{
+			name:  "not RIFF",
+			bytes: []byte("ID3\x03\x00\x00\x00\x00\x00\x00\x00\x00"),
+			want:  riff.ErrNotRIFF,
+		},
+		{
+			name:  "not WAVE",
+			bytes: buildRIFF("RIFF", "AVI ", []chunk{{id: "id3 ", data: []byte("x")}}),
+			want:  riff.ErrNotWAVE,
+		},
+		{
+			name:  "RF64",
+			bytes: buildRIFF("RF64", "WAVE", []chunk{{id: "id3 ", data: []byte("x")}}),
+			want:  riff.ErrRF64NotSupported,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := riff.ID3Chunk(bytes.NewReader(tc.bytes))
+			if !errors.Is(err, tc.want) {
+				t.Errorf("ID3Chunk error: got %v, want %v", err, tc.want)
+			}
+		})
+	}
+}
+
+// A file cut short mid-chunk is a file with no tag, not a reason to
+// allocate the size it claims: the declared size is four bytes any
+// truncation can leave saying 4 GB.
+func TestID3Chunk_ToleratesATruncatedFile(t *testing.T) {
+	t.Parallel()
+
+	full := buildRIFF("RIFF", "WAVE", []chunk{
+		{id: "data", data: make([]byte, 64)},
+		{id: "id3 ", data: []byte("tag")},
+	})
+
+	t.Run("cut inside the audio", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := riff.ID3Chunk(bytes.NewReader(full[:32]))
+		if !errors.Is(err, riff.ErrNoID3Chunk) {
+			t.Errorf("ID3Chunk error: got %v, want %v", err, riff.ErrNoID3Chunk)
+		}
+	})
+
+	t.Run("cut inside the tag", func(t *testing.T) {
+		t.Parallel()
+
+		if _, err := riff.ID3Chunk(bytes.NewReader(full[:len(full)-2])); err == nil {
+			t.Error("ID3Chunk: got nil error for a truncated tag chunk")
+		}
+	})
+}
+
+// Parse is the writer's half and reads every chunk into memory, which
+// is what preserving them needs.
+func TestParse_ReadsEveryChunkInOrder(t *testing.T) {
+	t.Parallel()
+
+	raw := buildRIFF("RIFF", "WAVE", []chunk{
+		{id: "fmt ", data: make([]byte, 16)},
+		{id: "LIST", data: []byte("INFOodd")},
+		{id: "id3 ", data: []byte("tag")},
+	})
+
+	chunks, err := riff.Parse(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+
+	want := []string{"fmt ", "LIST", "id3 "}
+	if len(chunks) != len(want) {
+		t.Fatalf("chunk count: got %d, want %d", len(chunks), len(want))
+	}
+
+	for i, id := range want {
+		if got := string(chunks[i].ID[:]); got != id {
+			t.Errorf("chunk %d: got %q, want %q", i, got, id)
+		}
+	}
+
+	if !riff.IsID3(chunks[2].ID) || string(chunks[2].Data) != "tag" {
+		t.Errorf("id3 chunk: got %q", chunks[2].Data)
+	}
+
+	// The padding byte after an odd chunk is not part of its data.
+	if string(chunks[1].Data) != "INFOodd" {
+		t.Errorf("odd chunk data: got %q, want %q", chunks[1].Data, "INFOodd")
+	}
+}
+
+// A chunk size is four bytes read off the file, so a truncated or
+// malformed WAV is free to declare a chunk larger than the whole of
+// itself.  Parse must grow with what arrives rather than with what was
+// claimed.
+//
+// This measures the allocation instead of the error because the error
+// is the same either way: a build sizing its buffer from the header
+// reports the truncation correctly, having asked the allocator for a
+// gigabyte on the way.  Deliberately not parallel — TotalAlloc is
+// process-wide, and a test paused beside another one is measuring it
+// too.
+func TestParse_DoesNotAllocateWhatAChunkClaims(t *testing.T) {
+	// Large enough that a header-sized buffer is unmistakable, in a
+	// container of a few dozen bytes.
+	const declared = 1 << 30
+
+	var raw bytes.Buffer
+
+	raw.WriteString("RIFF")
+	_ = binary.Write(&raw, binary.LittleEndian, uint32(declared+12))
+	raw.WriteString("WAVE")
+	raw.WriteString("data")
+	_ = binary.Write(&raw, binary.LittleEndian, uint32(declared))
+	raw.WriteString("and then the file ends")
+
+	var before, after runtime.MemStats
+
+	runtime.GC()
+	runtime.ReadMemStats(&before)
+
+	if _, err := riff.Parse(bytes.NewReader(raw.Bytes())); err == nil {
+		t.Fatal("Parse: got nil error for a chunk larger than the file holding it")
+	}
+
+	runtime.ReadMemStats(&after)
+
+	if grew := after.TotalAlloc - before.TotalAlloc; grew > 1<<20 {
+		t.Errorf("Parse allocated %d bytes reading a %d-byte file whose chunk header claimed %d",
+			grew, raw.Len(), declared)
+	}
+}

backend/system/userdata.go

@@ -52,6 +52,75 @@ func UseHomeOverride(base string) {
 	_ = os.Setenv(envHomeOverride, base)
 }
 
+// envTempDir is the variable Go's os.TempDir() reads, and through it
+// every library in the process that asks for a temporary file.
+const envTempDir = "TMPDIR"
+
+// tempDirName is the subdirectory of the app's own storage that
+// becomes that answer.
+const tempDirName = "tmp"
+
+// UseTempDir gives the process a temporary directory that exists.
+//
+// **Android has no /tmp and hands an app no TMPDIR**, and Go's
+// os.TempDir() falls back to "/tmp" when the variable is unset -- so
+// every library in the process that wants scratch space is handed a
+// path that has never existed. SQLite is the one that noticed: an
+// INSERT ... SELECT large enough to spill returned
+// SQLITE_IOERR_GETTEMPPATH (disk I/O error 6410), which is how the
+// champion search index came to fail its rebuild on every launch while
+// the app otherwise looked healthy (#190).
+//
+// It is the *class* that is fixed here rather than that statement.
+// Anything that spills fails the same way on that platform -- large
+// sorts, large joins, VACUUM -- so the repair belongs at the process's
+// one answer to the question rather than at each caller. The
+// alternative considered was PRAGMA temp_store = MEMORY, which is
+// cheaper and more local and is a promise that every future spill fits
+// in RAM on a phone; the catalog is the largest thing in this app and
+// that is not a promise worth making silently.
+//
+// The rules are UseHomeOverride's, for the same reasons. **An empty
+// base is a no-op**, because that is what
+// application.Mobile.StoragePath() returns on desktop -- so this needs
+// no build tag and changes nothing off mobile, where /tmp is real. And
+// **an explicit TMPDIR wins**, so anyone who set one deliberately gets
+// what they asked for; nothing sets it on the platform this exists for.
+//
+// It returns its error rather than swallowing it because a temp
+// directory that could not be created is the same silent failure one
+// step earlier, and since #160 a log line on that platform is
+// something a person can actually read.
+func UseTempDir(base string) error {
+	if base == "" || os.Getenv(envTempDir) != "" {
+		return nil
+	}
+
+	dir := filepath.Join(base, tempDirName)
+
+	if err := os.MkdirAll(dir, os.ModePerm); err != nil {
+		return fmt.Errorf("could not make the temp directory %s: %w", dir, err)
+	}
+
+	// Writability is checked rather than assumed: the whole failure
+	// this repairs is a directory that is named and cannot be used, and
+	// MkdirAll on an existing unwritable directory succeeds.
+	probe, err := os.CreateTemp(dir, "probe")
+	if err != nil {
+		return fmt.Errorf("temp directory %s is not writable: %w", dir, err)
+	}
+
+	name := probe.Name()
+	_ = probe.Close()
+	_ = os.Remove(name)
+
+	if err := os.Setenv(envTempDir, dir); err != nil {
+		return fmt.Errorf("could not set %s: %w", envTempDir, err)
+	}
+
+	return nil
+}
+
 // getUserDirPath returns and creates the path for a user directory.
 func getUserDirPath(dt dirType) (string, error) {
 	path, err := resolveUserDirPath(dt)

backend/system/userdata_test.go

@@ -87,3 +87,116 @@ func TestUseHomeOverride(t *testing.T) {
 		})
 	}
 }
+
+// UseTempDir carries UseHomeOverride's two rules for the same reasons,
+// plus one of its own: the directory it names has to be usable.
+//
+// **The only tier that can compile the platform this exists for is a
+// phone**, so everything decidable off one is decided here -- which is
+// androidpayload.go's discipline, and is why the platform call is a
+// parameter rather than something this package reaches for. The
+// device's half is a single measurement: no /tmp, no TMPDIR (#190).
+func TestUseTempDir(t *testing.T) {
+	t.Run("an empty base is a no-op", func(t *testing.T) {
+		// This is the desktop case in full: StoragePath() answers ""
+		// off mobile, where /tmp is real and must be left alone.
+		t.Setenv(envTempDir, "")
+
+		if err := UseTempDir(""); err != nil {
+			t.Fatalf("UseTempDir(\"\") = %v, want nil", err)
+		}
+
+		if got := os.Getenv(envTempDir); got != "" {
+			t.Errorf("%s = %q, want it untouched", envTempDir, got)
+		}
+	})
+
+	t.Run("an explicit TMPDIR wins", func(t *testing.T) {
+		const chosen = "/somewhere/deliberate"
+
+		// The base is taken before TMPDIR moves, because t.TempDir()
+		// reads TMPDIR too -- which is the same fact this function is
+		// about, met from the other side.
+		base := t.TempDir()
+
+		t.Setenv(envTempDir, chosen)
+
+		if err := UseTempDir(base); err != nil {
+			t.Fatalf("UseTempDir = %v, want nil", err)
+		}
+
+		if got := os.Getenv(envTempDir); got != chosen {
+			t.Errorf("%s = %q, want the explicit %q", envTempDir, got, chosen)
+		}
+	})
+
+	t.Run("points at a real directory under the base", func(t *testing.T) {
+		base := t.TempDir()
+
+		t.Setenv(envTempDir, "")
+
+		if err := UseTempDir(base); err != nil {
+			t.Fatalf("UseTempDir = %v, want nil", err)
+		}
+
+		got := os.Getenv(envTempDir)
+
+		want := filepath.Join(base, tempDirName)
+		if got != want {
+			t.Fatalf("%s = %q, want %q", envTempDir, got, want)
+		}
+
+		// The whole failure being repaired is a temp directory that is
+		// named and does not exist, so naming one is not enough.
+		info, err := os.Stat(got)
+		if err != nil {
+			t.Fatalf("the temp directory was named but not created: %v", err)
+		}
+
+		if !info.IsDir() {
+			t.Fatalf("%s is not a directory", got)
+		}
+	})
+
+	t.Run("os.TempDir then answers with it", func(t *testing.T) {
+		// The point of setting the variable at all: this is what every
+		// library in the process reads, SQLite's driver included.
+		base := t.TempDir()
+
+		t.Setenv(envTempDir, "")
+
+		if err := UseTempDir(base); err != nil {
+			t.Fatalf("UseTempDir = %v, want nil", err)
+		}
+
+		if got := os.TempDir(); got != filepath.Join(base, tempDirName) {
+			t.Errorf("os.TempDir() = %q, want the directory we made", got)
+		}
+	})
+
+	t.Run("an unwritable directory is an error, not a silent success", func(t *testing.T) {
+		if os.Getuid() == 0 {
+			t.Skip("root can write anywhere, so there is nothing to refuse")
+		}
+
+		base := t.TempDir()
+
+		// MkdirAll on an existing directory succeeds whatever its
+		// mode, so without the write probe this case would set TMPDIR
+		// to a directory nothing can use -- which is the bug again,
+		// one directory over.
+		if err := os.Mkdir(filepath.Join(base, tempDirName), 0o500); err != nil {
+			t.Fatalf("prepare the unwritable directory: %v", err)
+		}
+
+		t.Setenv(envTempDir, "")
+
+		if err := UseTempDir(base); err == nil {
+			t.Fatal("UseTempDir accepted a directory it cannot write to")
+		}
+
+		if got := os.Getenv(envTempDir); got != "" {
+			t.Errorf("%s was set to %q despite the failure", envTempDir, got)
+		}
+	})
+}

backend/tagwriter/totals_test.go

@@ -13,9 +13,10 @@ import (
 // indistinguishable from never having written one.  So these assert the
 // round trip through the *reader the scan uses*, not the bytes.
 //
-// WAV is the exception and it is not this change's: dhowden/tag has no
-// RIFF reader at all, so metadata.ExtractTags cannot see a WAV's ID3
-// chunk -- which is why every other test here reads that chunk itself.
+// WAV was the exception until #104 -- dhowden/tag has no RIFF reader,
+// so metadata.ExtractTags could not see a WAV's ID3 chunk and this
+// case read the chunk itself, which is a test of the writer wearing
+// the shape of a round trip.  All four go through the scanner now.
 func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
 	t.Parallel()
 
@@ -91,7 +92,7 @@ func TestWriteTotals_RoundTripsInEveryFormat(t *testing.T) {
 		},
 		{
 			name: "wav",
-			read: readWavID3Tags,
+			read: viaScanner,
 			write: func(t *testing.T, dir string) string {
 				t.Helper()
 

backend/tagwriter/wav.go

@@ -8,116 +8,22 @@ import (
 	"io"
 	"log/slog"
 	"os"
-	"strings"
 
 	id3v2 "github.com/bogem/id3v2/v2"
 
 	"yellowjacket/backend/fileutil"
+	"yellowjacket/backend/riff"
 )
 
-// Sentinel errors for WAV RIFF operations.
-var (
-	errRF64NotSupported   = errors.New("RF64 files are not yet supported")
-	errNotRIFF            = errors.New("not a RIFF file")
-	errNotWAVE            = errors.New("not a WAVE file")
-	errFileTooLargeForWAV = errors.New("file too large for WAV format (>4GB)")
-)
-
-// riffChunk holds a single RIFF sub-chunk (ID + raw data).
-type riffChunk struct {
-	id   [4]byte
-	data []byte
-}
-
-// parseRIFF reads all RIFF sub-chunks from r.  It rejects RF64 files
-// and non-WAVE containers with descriptive errors.  The parser is
-// lenient on read: it tolerates missing padding bytes and ignores
-// the declared RIFF size.
-func parseRIFF(r io.ReadSeeker) ([]riffChunk, error) {
-	// Read 4-byte container magic.
-	var magic [4]byte
-	if _, err := io.ReadFull(r, magic[:]); err != nil {
-		return nil, fmt.Errorf("read RIFF magic: %w", err)
-	}
-
-	if string(magic[:]) == "RF64" {
-		return nil, errRF64NotSupported
-	}
-
-	if string(magic[:]) != "RIFF" {
-		return nil, fmt.Errorf("%w: got %q", errNotRIFF, magic)
-	}
-
-	// Read (and discard) RIFF size — lenient, do not enforce.
-	var riffSize uint32
-	if err := binary.Read(r, binary.LittleEndian, &riffSize); err != nil {
-		return nil, fmt.Errorf("read RIFF size: %w", err)
-	}
-
-	// Read 4-byte form type.
-	var form [4]byte
-	if _, err := io.ReadFull(r, form[:]); err != nil {
-		return nil, fmt.Errorf("read WAVE form type: %w", err)
-	}
-
-	if string(form[:]) != "WAVE" {
-		return nil, fmt.Errorf("%w: got %q", errNotWAVE, form)
-	}
-
-	// Read sub-chunks until EOF.
-	var chunks []riffChunk
-
-	for {
-		var chunkID [4]byte
-
-		_, err := io.ReadFull(r, chunkID[:])
-		if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
-			break
-		}
-
-		if err != nil {
-			return nil, fmt.Errorf("read chunk ID: %w", err)
-		}
-
-		var chunkSize uint32
-		if err := binary.Read(r, binary.LittleEndian, &chunkSize); err != nil {
-			return nil, fmt.Errorf("read chunk size for %q: %w", chunkID, err)
-		}
-
-		data := make([]byte, chunkSize)
-		if _, err := io.ReadFull(r, data); err != nil {
-			return nil, fmt.Errorf("read chunk data for %q: %w", chunkID, err)
-		}
-
-		chunks = append(chunks, riffChunk{id: chunkID, data: data})
-
-		// Odd-length chunks have a padding byte.  Lenient: if the
-		// read fails (e.g. EOF), just break rather than error.
-		if chunkSize%2 != 0 {
-			var pad [1]byte
-
-			if _, err := r.Read(pad[:]); err != nil {
-				break
-			}
-		}
-	}
-
-	return chunks, nil
-}
-
-// isID3ChunkID returns true if id represents an ID3v2 RIFF chunk.
-// Both lowercase "id3 " and uppercase "ID3 " are accepted.
-func isID3ChunkID(id [4]byte) bool {
-	s := strings.ToLower(string(id[:3]))
-
-	return s == "id3"
-}
+// errFileTooLargeForWAV is the one RIFF error that belongs to the
+// writer; reading rejects a container in backend/riff.
+var errFileTooLargeForWAV = errors.New("file too large for WAV format (>4GB)")
 
 // writeRIFF writes a complete RIFF/WAVE container to w, preserving
 // the given chunks in order and appending the id3Data as the final
 // "id3 " chunk.  Returns errFileTooLargeForWAV if the result would
 // exceed the 4 GB RIFF limit.
-func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
+func writeRIFF(w io.Writer, chunks []riff.Chunk, id3Data []byte) error {
 	// Calculate total RIFF payload size:
 	//   4 bytes (WAVE form type)
 	// + for each preserved chunk: 8 (header) + len(data) + padding
@@ -125,7 +31,7 @@ func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
 	riffPayload := uint64(4)
 
 	for _, c := range chunks {
-		sz := uint64(len(c.data))
+		sz := uint64(len(c.Data))
 		riffPayload += 8 + sz
 
 		if sz%2 != 0 {
@@ -162,7 +68,7 @@ func writeRIFF(w io.Writer, chunks []riffChunk, id3Data []byte) error {
 
 	// Write each preserved chunk.
 	for _, c := range chunks {
-		if err := writeChunk(w, c.id, c.data); err != nil {
+		if err := writeChunk(w, c.ID, c.Data); err != nil {
 			return err
 		}
 	}
@@ -225,7 +131,7 @@ func writeWavTags(
 		return fmt.Errorf("open wav for reading: %w", err)
 	}
 
-	allChunks, err := parseRIFF(f)
+	allChunks, err := riff.Parse(f)
 
 	// Close immediately — we need the handle released before
 	// AtomicWrite creates the replacement file.
@@ -237,13 +143,13 @@ func writeWavTags(
 
 	// Separate preserved chunks from existing ID3 data.
 	var (
-		preserved   []riffChunk
+		preserved   []riff.Chunk
 		existingID3 []byte
 	)
 
 	for _, c := range allChunks {
-		if isID3ChunkID(c.id) {
-			existingID3 = c.data
+		if riff.IsID3(c.ID) {
+			existingID3 = c.Data
 		} else {
 			preserved = append(preserved, c)
 		}

backend/tagwriter/wav_test.go

@@ -12,6 +12,7 @@ import (
 	id3v2 "github.com/bogem/id3v2/v2"
 
 	"yellowjacket/backend/metadata"
+	"yellowjacket/backend/riff"
 )
 
 // createTestWAV builds a minimal valid WAV file with an optional
@@ -270,6 +271,88 @@ func TestWriteWavTags_PartialUpdate(t *testing.T) {
 	assertStrField(t, "Composer", meta.Composer, "Original Composer")
 }
 
+// The writer has always been correct and the reader could not see it:
+// a WAV tagged by this app scanned as an untagged file, so editing
+// tags, autotagging a folder or importing a WAV download all appeared
+// to work and changed nothing the library could show (#104).  So this
+// asserts the write through metadata.ExtractTags -- the reader the
+// scan uses -- rather than through the id3 chunk.
+func TestWriteWavTags_ReadBackByTheScanner(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	path := createTestWAV(t, dir, "scanner.wav", nil)
+	art := tinyJPEG(t)
+
+	changes := TagChanges{
+		FieldTitle:       "Some Song",
+		FieldArtist:      "Some Artist",
+		FieldAlbum:       "Some Album",
+		FieldAlbumArtist: "Some Album Artist",
+		FieldGenre:       "Rock",
+		FieldYear:        2024,
+		FieldTrackNumber: 3,
+		FieldComposer:    "Some Composer",
+		FieldCoverArt:    art,
+	}
+
+	if err := writeWavTags(testLogger(), path, changes); err != nil {
+		t.Fatalf("writeWavTags: %v", err)
+	}
+
+	meta, err := metadata.ExtractTags(path)
+	if err != nil {
+		t.Fatalf("ExtractTags: %v", err)
+	}
+
+	if meta.TagReadWarning != nil {
+		t.Errorf("TagReadWarning: %v", meta.TagReadWarning)
+	}
+
+	assertStrField(t, "Title", meta.Title, "Some Song")
+	assertStrField(t, "Artist", meta.Artist, "Some Artist")
+	assertStrField(t, "Album", meta.Album, "Some Album")
+	assertStrField(t, "AlbumArtist", meta.AlbumArtist, "Some Album Artist")
+	assertStrField(t, "Genre", meta.Genre, "Rock")
+	assertStrField(t, "Composer", meta.Composer, "Some Composer")
+	assertStrField(t, "FileFormat", meta.FileFormat, "WAV")
+	assertIntField(t, "Year", meta.Year, 2024)
+	assertIntField(t, "TrackNumber", meta.TrackNumber, 3)
+
+	if !strings.HasPrefix(meta.TagFormat, "ID3v2") {
+		t.Errorf("TagFormat: got %q, want an ID3v2 version", meta.TagFormat)
+	}
+
+	if meta.Picture == nil {
+		t.Fatal("expected cover art, got nil")
+	}
+
+	if !bytes.Equal(meta.Picture.Data, art) {
+		t.Errorf("picture data mismatch: got %d bytes, want %d",
+			len(meta.Picture.Data), len(art))
+	}
+}
+
+// An untagged WAV is a file with no tags, not a file with a problem:
+// the scanner falls back to the filename and must not be handed a
+// warning to surface about it.
+func TestUntaggedWav_ReadsAsEmptyWithoutAWarning(t *testing.T) {
+	t.Parallel()
+
+	path := createTestWAV(t, t.TempDir(), "bare.wav", nil)
+
+	meta, err := metadata.ExtractTags(path)
+	if err != nil {
+		t.Fatalf("ExtractTags: %v", err)
+	}
+
+	if meta.TagReadWarning != nil {
+		t.Errorf("TagReadWarning: %v", meta.TagReadWarning)
+	}
+
+	assertStrField(t, "Title", meta.Title, "")
+}
+
 func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	t.Parallel()
 
@@ -282,7 +365,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 		t.Fatalf("open original: %v", err)
 	}
 
-	origChunks, err := parseRIFF(origFile)
+	origChunks, err := riff.Parse(origFile)
 	_ = origFile.Close()
 
 	if err != nil {
@@ -292,7 +375,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	// Record original chunk data by ID string.
 	origData := map[string][]byte{}
 	for _, c := range origChunks {
-		origData[string(c.id[:])] = c.data
+		origData[string(c.ID[:])] = c.Data
 	}
 
 	// Write a tag to trigger RIFF rewrite.
@@ -309,7 +392,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 		t.Fatalf("open after write: %v", err)
 	}
 
-	newChunks, err := parseRIFF(newFile)
+	newChunks, err := riff.Parse(newFile)
 	_ = newFile.Close()
 
 	if err != nil {
@@ -320,7 +403,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	origNonID3 := 0
 
 	for _, c := range origChunks {
-		if !isID3ChunkID(c.id) {
+		if !riff.IsID3(c.ID) {
 			origNonID3++
 		}
 	}
@@ -328,7 +411,7 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 	newNonID3 := 0
 
 	for _, c := range newChunks {
-		if !isID3ChunkID(c.id) {
+		if !riff.IsID3(c.ID) {
 			newNonID3++
 		}
 	}
@@ -359,17 +442,17 @@ func TestWriteWavTags_ChunkPreservation(t *testing.T) {
 // in chunks and its data matches want byte-for-byte.
 func checkChunkPreserved(
 	t *testing.T,
-	chunks []riffChunk,
+	chunks []riff.Chunk,
 	idStr string,
 	want []byte,
 ) {
 	t.Helper()
 
 	for _, c := range chunks {
-		if string(c.id[:]) == idStr {
-			if !bytes.Equal(c.data, want) {
+		if string(c.ID[:]) == idStr {
+			if !bytes.Equal(c.Data, want) {
 				t.Errorf("chunk %q data changed: got %d bytes, want %d",
-					idStr, len(c.data), len(want))
+					idStr, len(c.Data), len(want))
 			}
 
 			return
@@ -430,7 +513,7 @@ func TestWriteWavTags_RejectsRF64(t *testing.T) {
 	buf.WriteString("WAVE")
 
 	// Minimal ds64 chunk (required for RF64 but we just need
-	// enough bytes for parseRIFF to hit the RF64 rejection).
+	// enough bytes for riff.Parse to hit the RF64 rejection).
 	buf.WriteString("ds64")
 	_ = binary.Write(&buf, binary.LittleEndian, uint32(28)) //nolint:mnd
 	buf.Write(make([]byte, 28))                             //nolint:mnd
@@ -454,9 +537,12 @@ func TestWriteWavTags_RejectsRF64(t *testing.T) {
 
 // readWavID3Tags extracts ID3v2 metadata from a WAV file by parsing
 // the RIFF structure and reading the id3 chunk with bogem/id3v2.
-// dhowden/tag's ReadFrom does not support WAV files, and its
-// ReadID3v2Tags fails on empty tags (after clearing all frames).
-// Using bogem/id3v2.ParseReader handles all cases correctly.
+//
+// metadata.ExtractTags reads a WAV since #104 and is what the round
+// trips assert through.  This stays for the two cases that are about
+// the bytes rather than about the scan: a tag with every frame
+// cleared, which no reader reports as anything, and the chunk
+// preservation test, which is already parsing the container itself.
 func readWavID3Tags(
 	t *testing.T,
 	path string,
@@ -470,17 +556,17 @@ func readWavID3Tags(
 
 	defer func() { _ = f.Close() }()
 
-	chunks, err := parseRIFF(f)
+	chunks, err := riff.Parse(f)
 	if err != nil {
-		t.Fatalf("parseRIFF: %v", err)
+		t.Fatalf("riff.Parse: %v", err)
 	}
 
 	// Find the id3 chunk.
 	var id3Data []byte
 
 	for _, c := range chunks {
-		if isID3ChunkID(c.id) {
-			id3Data = c.data
+		if riff.IsID3(c.ID) {
+			id3Data = c.Data
 
 			break
 		}

build/android/Taskfile.yml

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

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

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

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

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

e2e/specs/bottom-bar.spec.ts

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

e2e/specs/control-names.spec.ts

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

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

@@ -42,10 +42,10 @@ const ACTIONS = ['Import', 'New Playlist', 'New Smart Playlist'];
  * 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 headerFit = (page: import('@playwright/test').Page, view = 'playlist-view') =>
+  page.evaluate((tag) => {
     const root = document
-      .querySelector('[data-testid="main-content"] playlist-view')
+      .querySelector(`[data-testid="main-content"] ${tag}`)
       ?.shadowRoot?.querySelector('page-header')?.shadowRoot;
 
     if (!root) return null;
@@ -76,7 +76,7 @@ const headerFit = (page: import('@playwright/test').Page) =>
         ...root.querySelectorAll('#page-header-overflow wa-dropdown-item'),
       ].map((i) => i.textContent?.trim() ?? ''),
     };
-  });
+  }, view);
 
 test.describe('the page header never clips an action', () => {
   test.beforeEach(async ({ app }) => {
@@ -316,3 +316,58 @@ test.describe('the page header never clips an action', () => {
     await expect.poll(async () => (await headerFit(app))?.menu).toEqual([]);
   });
 });
+
+/**
+ * The Tracks header carries the play-all/shuffle-all pair (#31), so
+ * the promise above has to hold for it too — the same per-button
+ * measurement, one view over. Its two actions are the whole of the
+ * header's declared set, and the pair is what plays the list the row
+ * is in, so a button rendered 20px of its 90px is a queue of nothing.
+ */
+const TRACK_ACTIONS = ['Play all', 'Shuffle all'];
+
+test.describe('the Tracks header never clips an action', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.getByTestId('nav-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+  });
+
+  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 });
+
+      await expect
+        .poll(async () => (await headerFit(app, 'track-list'))?.clipped)
+        .toEqual([]);
+
+      const fit = (await headerFit(app, 'track-list'))!;
+
+      expect(fit.overflow).toBeLessThanOrEqual(0);
+
+      // Between them, buttons and menu account for both actions —
+      // not "it fits" but "nothing was dropped to make it fit".
+      expect([...fit.buttons, ...fit.menu].sort()).toEqual(
+        [...TRACK_ACTIONS].sort(),
+      );
+    });
+  }
+
+  /**
+   * The pair's names, through the accessibility tree — a shadow query
+   * measures, but it cannot say what a screen reader is offered.
+   */
+  test('both actions are named controls', async ({ app }) => {
+    for (const label of TRACK_ACTIONS) {
+      await expect(
+        app.getByRole('button', { name: label, exact: true }),
+      ).toBeVisible();
+    }
+  });
+});

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

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

e2e/specs/long-press.spec.ts

@@ -1,127 +0,0 @@
-import { test, expect } from '../support/fixtures.js';
-
-/**
- * Long-press is the touch route to a context menu (plan 016 B2 phase 3).
- *
- * The component tier proves the gesture in isolation, against markup it
- * built itself. What it cannot prove is the half that made this one
- * listener instead of six: that the synthetic event reaches the handler
- * a *real* component bound — `track-list` delegates its `contextmenu`
- * on the `lit-virtualizer` rather than binding one per row — and that
- * the real `wa-popup` menu opens from it, which is a path with its own
- * history of opening and then refusing to work (see
- * `menu-keyboard.spec.ts`).
- *
- * The pointer events are dispatched rather than performed: this project
- * runs Desktop Chrome and Desktop Safari, neither of which has touch,
- * and a device tier does not exist. So this is honest about what it
- * checks — the app's own listeners, on the app's own DOM, from the
- * events a touch would produce — and not about a real finger.
- */
-
-/** A common small phone, as in `phone-shell.spec.ts`. */
-const PHONE = { width: 390, height: 844 };
-
-/** Comfortably past the module's 500ms hold. */
-const HELD = 900;
-
-type Page = import('@playwright/test').Page;
-
-/** The track list's menu panel, or null while it is not rendered. */
-const panel = (page: Page) =>
-  page.evaluate(() => {
-    const el = document
-      .querySelector('track-list')
-      ?.shadowRoot?.querySelector('.context-menu-panel');
-
-    if (!el) return null;
-
-    return {
-      role: el.getAttribute('role'),
-      label: el.getAttribute('aria-label'),
-      items: el.querySelectorAll('[role="menuitem"]').length,
-    };
-  });
-
-/**
- * Press the first track row, optionally dragging partway through — the
- * shape of a scroll that begins on a row, which must not open a menu.
- */
-async function pressFirstRow(
-  page: Page,
-  opts: { driftY?: number } = {},
-): Promise<void> {
-  await page.evaluate((drift) => {
-    // `.track-row`, not `[role="row"]`: the column header is a row too,
-    // and it is the *first* one -- a press on it is correctly ignored,
-    // which reads exactly like the gesture not working.
-    const row = document
-      .querySelector('track-list')
-      ?.shadowRoot?.querySelector('.track-row');
-
-    if (!row) throw new Error('no track row to press');
-
-    const box = row.getBoundingClientRect();
-    const x = Math.round(box.left + box.width / 2);
-    const y = Math.round(box.top + box.height / 2);
-    const send = (type: string, dy = 0) =>
-      row.dispatchEvent(
-        new PointerEvent(type, {
-          bubbles: true,
-          composed: true,
-          cancelable: true,
-          pointerType: 'touch',
-          isPrimary: true,
-          clientX: x,
-          clientY: y + dy,
-        }),
-      );
-
-    send('pointerdown');
-
-    if (drift) send('pointermove', drift);
-  }, opts.driftY ?? 0);
-}
-
-test.describe('long-press opens the track menu', () => {
-  test.beforeEach(async ({ app }) => {
-    await app.setViewportSize(PHONE);
-    await app.getByTestId('tab-tracks').click();
-    await expect(app.getByTestId('main-content')).toHaveAttribute(
-      'data-active-view',
-      'tracks',
-    );
-  });
-
-  test.afterEach(async ({ app }) => {
-    // Every other spec file runs against a desktop, and the viewport
-    // belongs to the shared context rather than to this file.
-    await app.setViewportSize({ width: 1440, height: 900 });
-  });
-
-  test('reaches the delegated handler and opens the real menu', async ({
-    app,
-  }) => {
-    await expect.poll(() => panel(app)).toBeNull();
-
-    await pressFirstRow(app);
-
-    await expect
-      .poll(() => panel(app), { timeout: HELD + 2000 })
-      .toMatchObject({ role: 'menu', label: 'Track actions' });
-
-    // The same panel Shift+F10 opens, items and all -- not an empty
-    // popup that happened to become visible.
-    expect((await panel(app))?.items).toBeGreaterThan(0);
-  });
-
-  test('does not open one for a press that turns into a scroll', async ({
-    app,
-  }) => {
-    await pressFirstRow(app, { driftY: 40 });
-
-    await app.waitForTimeout(HELD);
-
-    expect(await panel(app)).toBeNull();
-  });
-});

e2e/specs/native-touch-feel.spec.ts

@@ -0,0 +1,140 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * The web view's own tap highlight, and what replaced it (#54).
+ *
+ * Two halves, and each is here because no other tier can see it.
+ *
+ * **The highlight is killed by one declaration on `html`**, which
+ * reaches the app's shadow roots because `-webkit-tap-highlight-color`
+ * is inherited and inheritance crosses a shadow boundary. That is a
+ * property of `index.css`, and `index.css` is loaded by the real app
+ * and by nothing else — the component tier mounts a component with no
+ * page stylesheet at all, which is the same reason the theme's ramps
+ * are invisible to it.
+ *
+ * **The press state is measured rather than read.** The component tier
+ * asserts the shape of the stylesheet (which rule is inside which
+ * query, and that the press selector carries a state class), because
+ * `:active` cannot be forced there. Here there is a real pointer: hold
+ * the button down on a real row of the real list and read what the row
+ * became. That is the assertion that would fail if the rule were
+ * hoisted, renamed, or lost to `.selected`.
+ *
+ * What neither half is, is the device. Chrome 113's WebView is where
+ * the grey box was reported and where a finger is; the numbers from it
+ * are on the PR.
+ */
+type Page = import('@playwright/test').Page;
+
+/** The phone this work was measured against, in CSS pixels. */
+const DEVICE = { width: 424, height: 439 };
+
+/** The computed tap-highlight colour of a node inside a shadow root. */
+const tapHighlight = (page: Page, host: string, inner: string) =>
+  page.evaluate(
+    ([hostSel, innerSel]) => {
+      const el = document
+        .querySelector(hostSel!)
+        ?.shadowRoot?.querySelector(innerSel!);
+
+      if (!el) return null;
+
+      return getComputedStyle(el).getPropertyValue(
+        '-webkit-tap-highlight-color',
+      );
+    },
+    [host, inner],
+  );
+
+test.describe('the tap highlight', () => {
+  test('is transparent inside a shadow root, from one rule on html', async ({
+    app,
+    browserName,
+  }) => {
+    await app.getByTestId('nav-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+
+    const row = await tapHighlight(app, 'track-list', '.track-row');
+
+    expect(row).not.toBeNull();
+
+    // The property is a WebKit extension that only iOS honours, so an
+    // engine is free not to report one at all. Chromium always does —
+    // measured at rgba(0, 0, 0, 0.18) with the rule removed, which is
+    // the grey box the report describes — so the assertion is not
+    // skippable there, and nothing this app can do makes the property
+    // disappear on an engine that has it.
+    test.skip(
+      row === '',
+      `${browserName} reports no -webkit-tap-highlight-color to read`,
+    );
+
+    expect(row).toBe('rgba(0, 0, 0, 0)');
+  });
+});
+
+test.describe('the press state that replaced it', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await app.getByTestId('tab-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+    await expect(app.locator('track-list').first()).toBeVisible();
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.mouse.up();
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  test('shows on the row being pressed, and on that row only', async ({
+    app,
+  }) => {
+    const rows = await app.evaluate(() => {
+      const found = document
+        .querySelector('track-list')
+        ?.shadowRoot?.querySelectorAll('.track-row');
+
+      if (!found || found.length < 2) return null;
+
+      const rect = found[1]!.getBoundingClientRect();
+
+      return {
+        x: Math.round(rect.x + rect.width / 2),
+        y: Math.round(rect.y + rect.height / 2),
+      };
+    });
+
+    expect(rows).not.toBeNull();
+
+    const backgrounds = () =>
+      app.evaluate(() => {
+        const found = document
+          .querySelector('track-list')!
+          .shadowRoot!.querySelectorAll('.track-row');
+
+        return {
+          pressed: getComputedStyle(found[1]!).backgroundColor,
+          neighbour: getComputedStyle(found[2]!).backgroundColor,
+        };
+      });
+
+    await app.mouse.move(rows!.x, rows!.y);
+    await app.mouse.down();
+
+    const held = await backgrounds();
+
+    // The press overlay, from the theme rather than from a literal in
+    // a component: rgba(255, 255, 255, 0.12) on both dark ramps.
+    expect(held.pressed).toBe('rgba(255, 255, 255, 0.12)');
+    expect(held.neighbour).not.toBe(held.pressed);
+
+    await app.mouse.up();
+  });
+});

e2e/specs/phone-album-page.spec.ts

@@ -0,0 +1,209 @@
+import { test, expect } from '../support/fixtures.js';
+import type { Page } from '@playwright/test';
+
+/**
+ * The album page on a phone (#66).
+ *
+ * Two faults, and neither was visible to `layout-overflow.spec.ts`:
+ * that spec asserts the *shell* needs no sideways scrolling, and the
+ * shell was correct throughout — `body.scrollWidth === clientWidth`
+ * while `explore-album-details` itself measured 443 inside a 424px box
+ * and clipped two of the album's three primary actions with its own
+ * `overflow: hidden`. So the measurement here is **per control against
+ * the component's box**, which is the same shape `top-bar-fit.spec.ts`
+ * needed for the same reason.
+ *
+ * The other half is the scroll: the page was a fixed header over a
+ * scrolling tracklist, so at the reference device's 424x439 the header
+ * owned 253 of the panel's 318px and the list scrolled in the 64 that
+ * were left. It is one scroll container below 600px, which is a
+ * property of the *host* rather than of `.content`.
+ *
+ * The engine is the caveat this tier cannot close: the reference device
+ * renders in Chrome 113 and this is Chromium/WebKit. A flex direction
+ * and a scroll container are nowhere near that engine's documented gaps
+ * (relaxed nesting, the Popover API, `light-dark()`), but "it renders
+ * at that size in Chromium" is not evidence about the phone.
+ */
+
+/** The phone this was measured on, in CSS pixels. */
+const DEVICE = { width: 424, height: 439 };
+
+const details = (page: Page) => page.locator('explore-album-details');
+
+/** The page's own boxes, read from inside its shadow root. */
+const geometry = (page: Page) =>
+  page.evaluate(() => {
+    const host = document.querySelector('explore-album-details');
+    const sr = host?.shadowRoot;
+
+    if (!host || !sr) return null;
+
+    const box = (sel: string) => {
+      const el = sr.querySelector(sel);
+
+      if (!el) return null;
+
+      const r = el.getBoundingClientRect();
+
+      return { width: Math.round(r.width), right: Math.round(r.right) };
+    };
+
+    const content = sr.querySelector('.content');
+
+    return {
+      hostWidth: host.clientWidth,
+      hostScrollWidth: host.scrollWidth,
+      // The host is the scroller below 600px, so the page is taller
+      // than its box rather than the tracklist being a window inside it.
+      hostScrolls: host.scrollHeight > host.clientHeight,
+      contentScrolls: content
+        ? content.scrollHeight > content.clientHeight
+        : null,
+      header: box('.album-header'),
+      play: box('[data-testid="album-play"]'),
+      shuffle: box('[data-testid="album-shuffle"]'),
+      queue: box('[data-testid="album-queue"]'),
+      title: (() => {
+        const el = sr.querySelector('.album-title-text');
+
+        return el ? el.scrollWidth <= el.clientWidth + 1 : null;
+      })(),
+    };
+  });
+
+test.describe('the album page on a phone', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await openFirstAlbum(app);
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+    await app.getByTestId('nav-tracks').click();
+  });
+
+  test('keeps every action inside its own box', async ({ app }) => {
+    const geo = await geometry(app);
+
+    expect(geo).not.toBeNull();
+    // "Shuffle album" ended at x=443 in a 424px component and could not
+    // be reached by any gesture; "Add to queue" at 440.
+    for (const action of ['play', 'shuffle', 'queue'] as const) {
+      expect(
+        geo?.[action],
+        `${action} is rendered`,
+      ).not.toBeNull();
+      expect(
+        geo?.[action]?.right ?? 0,
+        `${action} ends inside the page`,
+      ).toBeLessThanOrEqual(geo?.hostWidth ?? 0);
+    }
+
+    expect(geo?.hostScrollWidth).toBe(geo?.hostWidth);
+    expect(geo?.header?.width).toBe(geo?.hostWidth);
+  });
+
+  test('gives the title the row rather than one glyph of it', async ({
+    app,
+  }) => {
+    // `.album-info` was squeezed to 112px beside the art, so an album
+    // called *Glass Harbour* drew as `G…`. It carries `min-width: 0`
+    // and was shrinking as asked — the row had to stack.
+    expect(await geometry(app).then((g) => g?.title)).toBe(true);
+  });
+
+  test('scrolls as one page, with the header scrolling away', async ({
+    app,
+  }) => {
+    const before = await geometry(app);
+
+    expect(before?.hostScrolls).toBe(true);
+    expect(before?.contentScrolls).toBe(false);
+
+    const headerTop = () =>
+      app.evaluate(
+        () =>
+          document
+            .querySelector('explore-album-details')
+            ?.shadowRoot?.querySelector('.album-header')
+            ?.getBoundingClientRect().top ?? 0,
+      );
+
+    expect(await headerTop()).toBeGreaterThanOrEqual(0);
+
+    // A wheel gesture, not `scrollTop`: `overflow: hidden` still permits
+    // programmatic scrolling, so a probe that assigns it passes on the
+    // build this exists to fail.
+    await details(app).hover();
+    await app.mouse.wheel(0, 250);
+
+    await expect.poll(headerTop).toBeLessThan(-100);
+  });
+
+  test('is the desktop arrangement again above the breakpoint', async ({
+    app,
+  }) => {
+    await app.setViewportSize({ width: 1024, height: 800 });
+
+    // The same element, re-laid-out: one component with two
+    // arrangements, not a phone-only copy.
+    await expect
+      .poll(async () => (await geometry(app))?.hostScrolls)
+      .toBe(false);
+
+    const arrangement = await app.evaluate(() => {
+      const sr = document.querySelector('explore-album-details')?.shadowRoot;
+      const header = sr?.querySelector('.album-header');
+      const content = sr?.querySelector('.content');
+
+      return {
+        direction: header ? getComputedStyle(header).flexDirection : null,
+        contentOverflow: content ? getComputedStyle(content).overflowY : null,
+      };
+    });
+
+    expect(arrangement.direction).toBe('row');
+    expect(arrangement.contentOverflow).toBe('auto');
+  });
+});
+
+/** Albums → the second card, which navigates to the album page. */
+async function openFirstAlbum(app: Page): Promise<void> {
+  // Below 600px the sidebar is gone; the tab bar is the navigation.
+  await app.getByTestId('tab-albums').click();
+  await expect(app.getByTestId('main-content')).toHaveAttribute(
+    'data-active-view',
+    'albums',
+  );
+
+  await expect.poll(() => cardCount(app)).toBeGreaterThan(1);
+
+  // Dispatched rather than clicked: the card lives in a virtualizer
+  // inside a shadow root, and Enter expands the dropdown instead.
+  await app.evaluate(() => {
+    document
+      .querySelector('cover-grid')
+      ?.shadowRoot?.querySelectorAll('.album-card')[1]
+      ?.dispatchEvent(
+        new MouseEvent('click', { bubbles: true, composed: true }),
+      );
+  });
+
+  await expect(app.getByTestId('main-content')).toHaveAttribute(
+    'data-active-view',
+    'explore-album-details',
+  );
+  await expect(
+    details(app).locator('[data-testid="album-play"]'),
+  ).toBeVisible();
+}
+
+async function cardCount(app: Page): Promise<number> {
+  return app.evaluate(
+    () =>
+      document
+        .querySelector('cover-grid')
+        ?.shadowRoot?.querySelectorAll('.album-card').length ?? 0,
+  );
+}

e2e/specs/phone-entity-links.spec.ts

@@ -0,0 +1,135 @@
+import {
+  test,
+  expect,
+  callBinding,
+  openTheQueue,
+  NO_QUEUE_SOURCE,
+} from '../support/fixtures.js';
+import type { Page } from '@playwright/test';
+
+/**
+ * #67 — a name is not a link on a phone, and the menu is where it went.
+ *
+ * The queue panel is the surface this is visible on: its rows draw a
+ * track title and an artist credit as `explore-link`s at every width,
+ * unlike `track-list`, whose phone column set stacks title over artist
+ * as plain text already.
+ *
+ * **The pair is what makes either assertion mean anything.** A link
+ * that is gone and a menu item that never arrived is not a smaller
+ * affordance — it is a destination the phone cannot reach, which is
+ * what plan 018's "no action is unreachable at any supported size"
+ * refuses. So each test asserts the phone and the desktop in the same
+ * breath: text *and* an item here, a link *and* no item there.
+ *
+ * The desktop half is also the regression guard for the change: menus
+ * above the breakpoint must be exactly what they were, because the name
+ * beside them is still a link and a menu that repeats the row is
+ * furniture.
+ */
+
+/** The reference device's real viewport, not a resized desktop. */
+const DEVICE = { width: 424, height: 439 };
+
+/** Wide enough that the queue is a column beside the content. */
+const DESKTOP = { width: 1280, height: 800 };
+
+const row = (app: Page, index: number) =>
+  app.locator(`queue-panel .track-item[data-index="${index}"]`);
+
+/** The queue panel's own context menu, as a list of item labels. */
+async function menuLabels(app: Page): Promise<string[]> {
+  return app.evaluate(() =>
+    [
+      ...document
+        .querySelector('queue-panel')!
+        .shadowRoot!.querySelectorAll('wa-dropdown-item'),
+    ].map((item) => item.textContent?.replace(/\s+/g, ' ').trim() ?? ''),
+  );
+}
+
+/**
+ * Queue three tracks that have an album, for the reason
+ * `queue-selection.spec.ts` states at length: `explore-link` routes a
+ * title to its *album's* page and renders plain text where it cannot
+ * route, so a track with no album answers this file's question with
+ * the wrong "no link".
+ */
+async function queueThree(app: Page): Promise<void> {
+  const paths = await app.evaluate(async () => {
+    const tracks = (await window.__yjEvents.call(
+      'library.Library.GetTracks',
+      [0],
+      10_000,
+    )) as { FilePath: string; Album: string; ArtistName: string }[];
+
+    return tracks
+      .filter((t) => t.Album !== '' && t.ArtistName !== '')
+      .slice(0, 3)
+      .map((t) => t.FilePath);
+  });
+
+  await callBinding(app, 'queue.Queue.SetQueue', [
+    paths,
+    0,
+    false,
+    NO_QUEUE_SOURCE,
+  ]);
+}
+
+/** Open the row's context menu and read the items back. */
+async function openRowMenu(app: Page, index: number): Promise<string[]> {
+  await row(app, index).click({ button: 'right' });
+  await expect
+    .poll(async () => (await menuLabels(app)).length)
+    .toBeGreaterThan(0);
+
+  return menuLabels(app);
+}
+
+test.describe('an inline name and the menu that replaces it', () => {
+  test.afterEach(async ({ app }) => {
+    await app.keyboard.press('Escape');
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {
+      /* an empty queue is the state we were asking for */
+    });
+    await app.setViewportSize(DESKTOP);
+  });
+
+  test('a queue row is plain text on a phone and carries the destination', async ({
+    app,
+  }) => {
+    await app.setViewportSize(DEVICE);
+    await queueThree(app);
+    await openTheQueue(app);
+    await expect(row(app, 0)).toBeVisible();
+
+    // The name is text: nothing in the row is a link at all.
+    await expect(app.locator('queue-panel .track-item .explore-link')).toHaveCount(
+      0,
+    );
+
+    const labels = await openRowMenu(app, 0);
+
+    expect(labels).toContain('Go to Artist');
+    expect(labels).toContain('Go to Album');
+  });
+
+  test('the same row on a desktop is a link, and its menu is untouched', async ({
+    app,
+  }) => {
+    await app.setViewportSize(DESKTOP);
+    await queueThree(app);
+    await openTheQueue(app);
+    await expect(row(app, 0)).toBeVisible();
+
+    await expect(
+      row(app, 0).locator('.track-title .explore-link'),
+    ).toHaveCount(1);
+
+    const labels = await openRowMenu(app, 0);
+
+    expect(labels).not.toContain('Go to Artist');
+    expect(labels).not.toContain('Go to Album');
+  });
+});

e2e/specs/phone-now-playing.spec.ts

@@ -0,0 +1,283 @@
+import { test, expect } from '../support/fixtures.js';
+
+/**
+ * Now Playing on a short screen (#51).
+ *
+ * #51 asks for a layout that "survives" ~424x439 with the controls
+ * never scrolling off. #172 measured why it did not — the stacked
+ * layout's budget is fixed, so the art gets whatever is left, and that
+ * was 39px before #64 and 53px after it.
+ *
+ * **Two separate claims are asserted here, and only one of them is
+ * about the phone.**
+ *
+ * The first is that the art is *square*. It was not: `aspect-ratio` is
+ * specified not to re-derive the width when `max-height` clamps the
+ * height, so the art was drawn as a letterbox band and `object-fit:
+ * cover` cropped the cover to it — 264x53 on the reference device. The
+ * leftover only exceeds the width above ~843px of viewport, so this
+ * was every height from ~500 to ~843 as well: most phones, and any
+ * short window. That is ordinary CSS rather than a Chrome 113 quirk,
+ * so this tier can see it, and the heights below are chosen to cover
+ * the range rather than the one device.
+ *
+ * The second is the reflow: below 500px the art and the names sit side
+ * by side, which is what takes the art from 53px to 143px. That is
+ * asserted as a *relation between boxes* — the art beside the names,
+ * not above them — because the pixel count is a consequence of the
+ * arrangement and would pin this file to one device's chrome.
+ *
+ * **What this tier cannot see** is the device's engine: CI's Chromium
+ * and WebKit are current, and #60's clipping showed what that costs.
+ * Nothing here depends on Chrome 113 behaviour — the sizing rules were
+ * checked against the device itself, at column heights of 288, 300,
+ * 451, 600 and 800, and the numbers are on #51.
+ */
+type Page = import('@playwright/test').Page;
+
+/** The reference device's real viewport. */
+const DEVICE = { width: 424, height: 439 };
+
+/**
+ * A tall phone, above the reflow's 500px. Roughly a Pixel 7, which is
+ * #51's other named device and was not attached — so what is checked
+ * here is the layout it *should* get, not that device.
+ */
+const TALL_PHONE = { width: 412, height: 869 };
+
+/** Inside the crop's old range and above the reflow: a short window. */
+const SHORT_WINDOW = { width: 390, height: 700 };
+
+/**
+ * The height the layout reflows at. Written down once here because the
+ * specs have to know which arrangement to *wait* for, not only which
+ * to assert.
+ */
+const REFLOW_AT = 500;
+
+/** Put a track in the player, so the view has art and names to lay out. */
+async function stageATrack(page: Page): Promise<void> {
+  await page.evaluate(async () => {
+    const tracks = (await window.__yjEvents.call(
+      'library.Library.GetTracks',
+      [0],
+      10_000,
+    )) as { FilePath: string }[];
+
+    await window.__yjEvents.call(
+      'queue.Queue.SetQueue',
+      [tracks.slice(0, 4).map((t) => t.FilePath), 0, false, { type: '', id: 0, label: '' }],
+      10_000,
+    );
+  });
+}
+
+/** Open the full-screen view and wait for the shell to say so. */
+async function openNowPlaying(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    document.dispatchEvent(
+      new CustomEvent('navigate', {
+        detail: { view: 'now-playing' },
+        bubbles: true,
+      }),
+    );
+  });
+
+  await expect(page.getByTestId('main-content')).toHaveAttribute(
+    'data-active-view',
+    'now-playing',
+  );
+
+  // The attribute is the shell's bookkeeping and lands before the view
+  // has a track, so measuring on it alone races the first layout --
+  // which showed up as a 60x5 art on the first spec of a cold run.
+  //
+  // Waiting for a non-zero box is not enough on its own either: a
+  // previous test leaves the *other* arrangement on screen, and a
+  // stale column satisfies "has a size" perfectly. So the wait is for
+  // the arrangement this viewport should have, which is the thing
+  // every assertion below depends on. Found by this file passing one
+  // test at a time and failing in file order.
+  const wantRow = (page.viewportSize()?.height ?? 0) <= REFLOW_AT;
+
+  await page.waitForFunction(
+    (row: boolean) => {
+      const v = document.querySelector('now-playing-view');
+      const stack = v?.shadowRoot?.querySelector('.stack');
+      const el = v?.shadowRoot?.querySelector('.art img, .art .placeholder');
+      const t = v?.shadowRoot?.querySelector('.transport');
+
+      if (!el || !t) return false;
+
+      // A build with no `.stack` at all is the one before this change,
+      // and the squareness assertions are still meaningful against it
+      // -- so this waits for the arrangement only where there is one to
+      // wait for. Otherwise reverting the component to check that these
+      // tests bite produces eight timeouts instead of the measurements
+      // that make the case.
+      if (stack) {
+        const dir = getComputedStyle(stack).flexDirection;
+
+        if (dir !== (row ? 'row' : 'column')) return false;
+      }
+
+      const r = el.getBoundingClientRect();
+
+      return r.width > 0 && r.height > 0 && t.getBoundingClientRect().height > 0;
+    },
+    wantRow,
+  );
+}
+
+/**
+ * The boxes this file reasons about, read in one evaluate.
+ *
+ * It reaches into the view's shadow root rather than using locators
+ * because the question is geometric — where these boxes are *relative
+ * to each other* — and a testid per edge would be four locators and
+ * four round trips to say one thing.
+ */
+async function boxes(page: Page) {
+  return page.evaluate(() => {
+    const v = document.querySelector('now-playing-view');
+
+    if (!v || !v.shadowRoot) return null;
+
+    const rect = (sel: string) => {
+      const el = v.shadowRoot!.querySelector(sel);
+
+      if (!el) return null;
+
+      const r = el.getBoundingClientRect();
+
+      return {
+        left: r.left, right: r.right, top: r.top, bottom: r.bottom,
+        width: r.width, height: r.height,
+      };
+    };
+
+    return {
+      // Whichever of the two the track has; both carry the sizing.
+      art: rect('.art img') ?? rect('.art .placeholder'),
+      artBox: rect('.art'),
+      stack: rect('.stack'),
+      meta: rect('.meta'),
+      transport: rect('.transport'),
+      scrollHeight: v.scrollHeight,
+      clientHeight: v.clientHeight,
+    };
+  });
+}
+
+test.describe('Now Playing survives a short screen', () => {
+  test.beforeEach(async ({ app }) => {
+    await stageATrack(app);
+  });
+
+  /**
+   * The crop, at four heights spanning the range it covered. This is
+   * the assertion that fails on the build before this change: at
+   * 424x439 the art measured 264x53.
+   */
+  for (const vp of [DEVICE, SHORT_WINDOW, TALL_PHONE, { width: 900, height: 500 }]) {
+    test(`draws the art square at ${vp.width}x${vp.height}`, async ({ app }) => {
+      await app.setViewportSize(vp);
+      await openNowPlaying(app);
+
+      const b = await boxes(app);
+
+      expect(b, 'now-playing-view did not mount').not.toBeNull();
+      expect(b!.art, 'neither art nor placeholder rendered').not.toBeNull();
+
+      const { width, height } = b!.art!;
+
+      expect(width, 'the art has no width').toBeGreaterThan(0);
+      // One pixel of slack for sub-pixel layout, and no more: the
+      // defect this guards was a 5:1 band.
+      expect(
+        Math.abs(width - height),
+        `art is ${Math.round(width)}x${Math.round(height)}, not square`,
+      ).toBeLessThanOrEqual(1);
+    });
+  }
+
+  /**
+   * The promise #51 states and plan 018's matrix repeats. A floor on
+   * the art with the block scrolling was the other option on #172 and
+   * this is why it was not taken.
+   */
+  test('never scrolls the transport off the bottom', async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await openNowPlaying(app);
+
+    const b = await boxes(app);
+
+    expect(b!.transport!.bottom).toBeLessThanOrEqual(DEVICE.height);
+    expect(
+      b!.scrollHeight,
+      'the view scrolls, so the transport can be moved off screen',
+    ).toBeLessThanOrEqual(b!.clientHeight + 1);
+  });
+
+  /**
+   * The reflow itself, as a relation rather than a measurement: below
+   * 500px the names are *beside* the art, above it they are below.
+   */
+  test('puts the names beside the art below 500px', async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await openNowPlaying(app);
+
+    const b = await boxes(app);
+
+    expect(
+      b!.meta!.left,
+      'the names are not to the right of the art',
+    ).toBeGreaterThanOrEqual(b!.artBox!.right - 1);
+  });
+
+  test('keeps the names below the art on a tall phone', async ({ app }) => {
+    await app.setViewportSize(TALL_PHONE);
+    await openNowPlaying(app);
+
+    const b = await boxes(app);
+
+    expect(
+      b!.meta!.top,
+      'the names are not below the art',
+    ).toBeGreaterThanOrEqual(b!.artBox!.bottom - 1);
+  });
+
+  /**
+   * What the reflow actually does, stated as a mechanism rather than
+   * as a number: in a row the art is bounded by the row's *height*,
+   * so it fills it — where in a column it is the leftover after the
+   * names, which is what made it 53px.
+   *
+   * **The pixel count is deliberately not asserted here.** Two drafts
+   * tried. The first compared the art against the column's leftover
+   * computed from the boxes on screen and passed on the broken build,
+   * because the subtraction goes negative when the names are taller
+   * than the art — precisely the defect. The second put a floor of
+   * 100px on it, passed locally at 114 and **failed in CI at 64**: this
+   * app is long-lived, so a job staged by an earlier spec is still on
+   * screen, and the volume control renders here where it does not on
+   * Android. Both are chrome above and below this view, and both move
+   * the leftover. A test that asserts how much room CI happened to
+   * have is a test about the runner.
+   *
+   * The device numbers — 53px to 143px — are on #51, measured there,
+   * which is the only tier that can honestly produce them.
+   */
+  test('fills the row with the art rather than the leftover', async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await openNowPlaying(app);
+
+    const b = await boxes(app);
+
+    expect(b!.stack, 'there is no row to fill').not.toBeNull();
+    expect(
+      Math.abs(b!.artBox!.height - b!.stack!.height),
+      'the art does not fill the row, so it is still a leftover',
+    ).toBeLessThanOrEqual(1);
+  });
+});

e2e/specs/phone-progress-line.spec.ts

@@ -0,0 +1,136 @@
+import {
+  test,
+  expect,
+  callBinding,
+  resetEvents,
+  waitForEvent,
+  LONG_TRACK,
+  NO_QUEUE_SOURCE,
+} from '../support/fixtures.js';
+import type { Page } from '@playwright/test';
+
+/**
+ * The phone's progress line (#58).
+ *
+ * The component tier already pins what the line *says* — that it
+ * renders the backend's reported position and never a count of its own.
+ * What only a real shell can answer is **where it is**: the issue asks
+ * for a line on the border between the mini player and the tab bar, and
+ * "on the border" is two adjacencies in a grid that no component-level
+ * render has around it.
+ *
+ * It also asserts the line is not there on a desktop, which is the
+ * other half of the same fact: above 600px there is no tab bar for it
+ * to sit on the border of, and the bar carries a real seek bar.
+ */
+type Rect = { x: number; y: number; width: number; height: number };
+
+/** The reference device's real viewport. */
+const DEVICE = { width: 424, height: 439 };
+const DESKTOP = { width: 1280, height: 800 };
+
+async function rectOf(app: Page, selector: string): Promise<Rect | null> {
+  return app.evaluate((sel) => {
+    const el = document.querySelector(sel);
+
+    if (!el) return null;
+
+    const r = el.getBoundingClientRect();
+
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+  }, selector);
+}
+
+/**
+ * Put the 90-second fixture on and wait for the first position report.
+ *
+ * The long track rather than any track: every other fixture is 2-6
+ * seconds, which is shorter than the time this spec takes to measure
+ * three rectangles.
+ */
+async function play(app: Page): Promise<void> {
+  const tracks = await callBinding<{ FilePath: string; TrackName: string }[]>(
+    app,
+    'library.Library.GetTracks',
+    [0],
+  );
+
+  // `TrackName`, not `Title`: that is what the library model calls it.
+  const long = tracks.find((t) => t.TrackName === LONG_TRACK);
+
+  expect(long, `no fixture track named ${LONG_TRACK}`).toBeTruthy();
+
+  await callBinding(app, 'queue.Queue.Clear');
+  await resetEvents(app);
+  await callBinding(app, 'queue.Queue.SetQueue', [
+    [long!.FilePath],
+    0,
+    false,
+    NO_QUEUE_SOURCE,
+  ]);
+  await waitForEvent(app, 'QueueChanged');
+  await callBinding(app, 'queue.Queue.Play');
+  await waitForEvent(app, 'PlaybackPositionChanged', { timeoutMs: 15_000 });
+}
+
+test.describe('the progress line sits on the border between the bars', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(DEVICE);
+    await play(app);
+  });
+
+  /*
+   * Every test here starts a LONG_TRACK and the suite is workers: 1,
+   * fullyParallel: false against one long-lived app — so without this
+   * the four phone-* specs that follow alphabetically inherit a playing
+   * queue. phone-transport.spec.ts records where that lesson came from:
+   * the fault first showed up as a flake in a spec about something else.
+   */
+  test.afterEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {
+      /* already empty */
+    });
+    await app.setViewportSize(DESKTOP);
+  });
+
+  test('spans the width, between the mini player and the tab bar', async ({
+    app,
+  }) => {
+    const line = await rectOf(app, 'player-progress-line');
+    const bar = await rectOf(app, '.bottom-bar');
+    const nav = await rectOf(app, 'bottom-nav');
+
+    expect(line, 'no progress line on the phone').not.toBeNull();
+    expect(bar).not.toBeNull();
+    expect(nav).not.toBeNull();
+
+    // A border, not a band: 2px, the full width, and touching both.
+    expect(line!.height).toBeCloseTo(2, 0);
+    expect(line!.width).toBeCloseTo(bar!.width, 0);
+    expect(line!.y).toBeCloseTo(bar!.y + bar!.height, 0);
+    expect(nav!.y).toBeCloseTo(line!.y + line!.height, 0);
+  });
+
+  /**
+   * It is 2px on the top edge of the tab bar, which is exactly where a
+   * thumb aiming at a tab lands. A line that sometimes seeks is worse
+   * than one that never does, so it must take no part in hit testing
+   * at all.
+   */
+  test('takes no taps', async ({ app }) => {
+    const line = await rectOf(app, 'player-progress-line');
+
+    const hit = await app.evaluate(
+      ({ x, y }) => document.elementFromPoint(x, y)?.tagName ?? '',
+      { x: line!.x + line!.width / 2, y: line!.y + 1 },
+    );
+
+    expect(hit).not.toBe('PLAYER-PROGRESS-LINE');
+  });
+
+  test('is not there on a desktop', async ({ app }) => {
+    await app.setViewportSize(DESKTOP);
+
+    await expect(app.locator('player-progress-line')).toBeHidden();
+  });
+});

e2e/specs/phone-search.spec.ts

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

e2e/specs/phone-shell.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, LONG_TRACK } from '../support/fixtures.js';
 
 /**
  * The phone shell (plan 016 B2, phase 1).
@@ -98,6 +98,58 @@ test.describe('the shell on a phone', () => {
     ).toBeVisible();
   });
 
+  test('draws "More" as a sheet on the bottom edge (#71)', async ({ app }) => {
+    await app.getByTestId('tab-more').click();
+    await expect(app.getByTestId('nav-drawer').locator('app-sidebar'))
+      .toBeVisible();
+
+    // What the report is about is geometry, and geometry is what no
+    // other assertion here can see: the side drawer was a 200px column
+    // opening away from the thumb that asked for it, with the rest of
+    // its 400px band empty. Measured rather than screenshotted, since
+    // the failure is a number.
+    //
+    // Polled, because a sheet *arrives*: the drawer's show animation
+    // translates it a full height below the fold, so a measurement
+    // taken the moment its content is visible reports a box hanging
+    // 412px off the bottom of the screen. Asking for the settled
+    // number is the assertion; asking once is a race.
+    const measure = () => app.evaluate(() => {
+      const nav = document.querySelector('bottom-nav');
+      const drawer = nav?.shadowRoot?.querySelector('wa-drawer');
+      const dialog = drawer?.shadowRoot?.querySelector('[part~="dialog"]');
+      const sidebar = nav?.shadowRoot?.querySelector('app-sidebar');
+      const row = sidebar?.shadowRoot?.querySelector('li button');
+      const box = dialog?.getBoundingClientRect();
+
+      return {
+        left: Math.round(box?.left ?? -1),
+        right: Math.round(box?.right ?? -1),
+        bottom: Math.round(box?.bottom ?? -1),
+        height: Math.round(box?.height ?? -1),
+        row: Math.round(row?.getBoundingClientRect().height ?? -1),
+        viewport: [window.innerWidth, window.innerHeight],
+      };
+    });
+
+    await expect
+      .poll(async () => (await measure()).bottom)
+      .toBe(PHONE.height);
+
+    const sheet = await measure();
+
+    expect(sheet.left).toBe(0);
+    expect(sheet.right).toBe(sheet.viewport[0]);
+
+    // A surface covering the whole screen is a page, not a sheet --
+    // which is also what leaves an outside to tap on, the only pointer
+    // route out of it (#171 is the same question one surface over).
+    expect(sheet.height).toBeLessThan(sheet.viewport[1]);
+
+    // 48px rows, from #186's touch floor and #60's context sheet.
+    expect(sheet.row).toBeGreaterThanOrEqual(48);
+  });
+
   for (const vp of [PHONE, SMALL_PHONE]) {
     test(`does not scroll sideways at ${vp.width}×${vp.height}`, async ({ app }) => {
       await app.setViewportSize(vp);
@@ -130,6 +182,25 @@ test.describe('the shell on a phone', () => {
     // are here, and they are the *same* components -- this view
     // composes the transport rather than reimplementing it.
     await expect(app.locator('now-playing-view seek-bar')).toBeVisible();
+
+    // Volume is here **because the player says there is one** (#64),
+    // not because this is a phone. This tier is the platform that owns
+    // its own volume, so what it can assert is that the control's
+    // presence follows that answer -- an inverted polarity in
+    // `volume-style-store` fails here and in `bottom-bar.spec.ts`, and
+    // the *absent* branch is checked in the component tier, where the
+    // binding can be stubbed. Nothing here can reach the Android side.
+    const systemOwns = await app.evaluate(
+      async () =>
+        (await window.__yjEvents.call(
+          'player.Player.SystemOwnsVolume',
+          [],
+          5_000,
+        )) as boolean,
+    );
+
+    expect(systemOwns, 'this platform should own its own volume').toBe(false);
+
     await expect(app.locator('now-playing-view volume-control')).toBeVisible();
 
     // Back goes where the user came from, through the nav stack.
@@ -138,6 +209,78 @@ test.describe('the shell on a phone', () => {
       .toHaveAttribute('data-active-view', 'tracks');
   });
 
+  /**
+   * The same journey with a track that has **no cover art** (#150).
+   *
+   * The test above starts the *first* row of the track list, so which
+   * track it plays is the order the scan inserted them in — and the
+   * answer decided whether it passed. A track with artwork renders an
+   * `<img>`, which is no obstacle; one without renders a placeholder
+   * `wa-icon`, which took every click aimed at the button beneath it,
+   * because that button is absolutely positioned with `z-index: auto`
+   * and the art is a *later* sibling. They tied, and the later one won.
+   *
+   * So this picks a track *for* the property that broke it, which is
+   * the only way the assertion means anything: the version above passes
+   * on a broken build roughly two runs in three, which is exactly how
+   * it came to cost three CI cycles across two branches that could not
+   * have caused it.
+   */
+  test('opens the full-screen now playing for a track with no art', async ({
+    app,
+  }) => {
+    // `LONG_TRACK` by name, and not "the first track with no
+    // CoverArt": the *library* model reports that field empty for
+    // every row in this fixture (31 of 31), so filtering on it selects
+    // nothing in particular and picked a 2-second track, which had
+    // finished before the assertions ran. The placeholder check below
+    // is what actually holds the property this test needs.
+    const started = await app.evaluate(async (longTitle) => {
+      const tracks = (await window.__yjEvents.call(
+        'library.Library.GetTracks',
+        [0],
+        10_000,
+      )) as { FilePath: string; TrackName: string }[];
+
+      const bare = tracks.find((t) => t.TrackName === longTitle);
+
+      if (!bare) return null;
+
+      await window.__yjEvents.call(
+        'queue.Queue.SetQueue',
+        [[bare.FilePath], 0, false, { type: '', id: 0, label: '' }],
+        10_000,
+      );
+      await window.__yjEvents.call('queue.Queue.Play', [], 5_000);
+
+      return bare.TrackName;
+    }, LONG_TRACK);
+
+    expect(started).toBe(LONG_TRACK);
+
+    await expect(app.getByTestId('now-playing-title')).not.toBeEmpty();
+
+    // **The placeholder is the whole point**, so it is asserted rather
+    // than assumed: this test is about the thing that renders when
+    // there is no artwork. If the fixture ever gives this album a
+    // cover, this fails and says so instead of passing while measuring
+    // the easy case.
+    //
+    // One selector rather than a chain from the host: Playwright's CSS
+    // engine pierces an open shadow root, and chaining from the host
+    // element does not reach into it.
+    await expect(
+      app.locator('now-playing .cover-placeholder'),
+    ).toBeAttached();
+
+    await app.getByTestId('open-now-playing').click();
+
+    await expect(app.getByTestId('main-content'))
+      .toHaveAttribute('data-active-view', 'now-playing');
+
+    await app.getByTestId('npv-back').click();
+  });
+
   test('offers no way in on a desktop, where the bar is whole', async ({ app }) => {
     await app.setViewportSize({ width: 1440, height: 900 });
 
@@ -154,9 +297,26 @@ test.describe('the shell on a phone', () => {
     await expect(app.locator('now-playing')).toBeVisible();
 
     // Volume is the hardware keys' job on a phone, and a 4px seek bar
-    // is not a thumb target -- both belong to a later phase's
-    // full-screen now-playing view.
-    await expect(app.locator('audio-player volume-control')).toBeHidden();
+    // is not a thumb target -- both belong to the full-screen
+    // now-playing view.
+    //
+    // `.bottom-bar volume-control`, not `audio-player volume-control`:
+    // #42 moved the control out of that component and into the bar, and
+    // **the old locator would have kept passing** — `toBeHidden()` is
+    // satisfied by an element that does not exist, so this assertion
+    // would have gone on reporting success about nothing. Its partner
+    // below is what makes this one mean something.
+    await expect(app.locator('.bottom-bar volume-control')).toBeHidden();
+
+    // The element is there and hidden, rather than absent: the check
+    // above cannot tell those apart on its own.
+    await expect(app.locator('.bottom-bar volume-control')).toHaveCount(1);
+
+    // And the seek bar is still inside the transport, where it stands
+    // down by its own media query.
+    await expect(
+      app.locator('audio-player').locator('seek-bar'),
+    ).toBeHidden();
   });
 });
 

e2e/specs/phone-transport.spec.ts

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

e2e/specs/play-all.spec.ts

@@ -0,0 +1,220 @@
+import { test, expect, callBinding, resetEvents, waitForEvent } from '../support/fixtures.js';
+
+type Page = import('@playwright/test').Page;
+
+/**
+ * Play-all/Shuffle-all, asserted on what the backend queued rather than
+ * on playback pixels.
+ *
+ * `SetQueue` reports the queue through `QueueChanged`, and `GetState`
+ * says exactly what it holds: the tracks in order, whether shuffle is
+ * on, and the `Source` the "Playing from" link is built from.  That is
+ * the honest contract here — the buttons are only as good as the queue
+ * they build, and the queue is only as good as the source it names.
+ */
+
+interface QueueState {
+  tracks: { filePath: string; title: string }[];
+  currentIndex: number;
+  shuffleMode: boolean;
+  source: { type: string; id: number; label: string };
+}
+
+const TRACKS_SOURCE = { type: 'tracks', id: 0, label: 'All Tracks' };
+
+const getQueue = (app: Page) =>
+  callBinding<QueueState>(app, 'queue.Queue.GetState');
+
+/** The track paths a rendered track list shows, in row order. */
+function displayedPaths(app: Page, scope: string): Promise<string[]> {
+  return app
+    .locator(`${scope} [data-testid="track-row"]`)
+    .evaluateAll((els) =>
+      els.map((el) => el.getAttribute('data-file-path') ?? ''),
+    );
+}
+
+/** Leave shuffle in a known state. The mode persists across specs in
+ *  one backend process, so a test that asserts on it has to set it. */
+async function setShuffleMode(app: Page, on: boolean): Promise<void> {
+  const state = await getQueue(app);
+
+  if (state.shuffleMode !== on) {
+    await resetEvents(app);
+    await callBinding(app, 'queue.Queue.ToggleShuffle');
+    await waitForEvent(app, 'QueueModeChanged');
+  }
+}
+
+test.describe('play-all/shuffle-all on the track list', () => {
+  test.beforeEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {
+      /* the queue is clearable on every build these specs run against */
+    });
+    await setShuffleMode(app, false);
+  });
+
+  test('Tracks Play all queues the displayed list with an honest source', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+    await expect(
+      app.locator('track-list [data-testid="track-row"]').first(),
+    ).toBeVisible();
+
+    const paths = await displayedPaths(app, 'track-list');
+
+    await resetEvents(app);
+    await app.getByTestId('page-action-play-all').click();
+    await waitForEvent(app, 'QueueChanged');
+
+    const state = await getQueue(app);
+
+    expect(state.tracks.map((t) => t.filePath)).toEqual(paths);
+    expect(state.currentIndex).toBe(0);
+    expect(state.shuffleMode).toBe(false);
+    expect(state.source).toEqual(TRACKS_SOURCE);
+  });
+
+  test('Tracks Shuffle all turns shuffle on and keeps the source', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-tracks').click();
+    await expect(
+      app.locator('track-list [data-testid="track-row"]').first(),
+    ).toBeVisible();
+
+    const paths = await displayedPaths(app, 'track-list');
+
+    await resetEvents(app);
+    await app.getByTestId('page-action-shuffle-all').click();
+    await waitForEvent(app, 'QueueChanged');
+
+    const state = await getQueue(app);
+
+    expect(state.tracks.map((t) => t.filePath)).toEqual(paths);
+    expect(state.shuffleMode).toBe(true);
+    expect(state.source).toEqual(TRACKS_SOURCE);
+  });
+});
+
+test.describe('play-all on an embedded track list', () => {
+  test.beforeEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {});
+    await setShuffleMode(app, false);
+  });
+
+  test('a genre page queues the genre with its name as the source', async ({
+    app,
+  }) => {
+    await app.getByTestId('nav-genres').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'genres',
+    );
+
+    const first = app.locator('genres-view .genre-card').first();
+
+    await expect(first).toBeVisible();
+    await first.click();
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'genre-details',
+    );
+    await expect(
+      app.locator('genre-details [data-testid="track-row"]').first(),
+    ).toBeVisible();
+
+    const genreName = (await app
+      .locator('genre-details .genre-title')
+      .textContent())?.trim();
+    const paths = await displayedPaths(app, 'genre-details');
+
+    await resetEvents(app);
+    await app
+      .locator('genre-details [data-testid="page-action-play-all"]')
+      .click();
+    await waitForEvent(app, 'QueueChanged');
+
+    const state = await getQueue(app);
+
+    expect(state.tracks.map((t) => t.filePath)).toEqual(paths);
+    expect(state.currentIndex).toBe(0);
+    expect(state.source).toEqual({ type: 'genre', id: 0, label: genreName });
+  });
+});
+
+test.describe('play-all on the library artist page', () => {
+  test.beforeEach(async ({ app }) => {
+    await callBinding(app, 'queue.Queue.Clear').catch(() => {});
+    await setShuffleMode(app, false);
+  });
+
+  test('an artist page queues album paths in album order with the artist source', async ({
+    app,
+  }) => {
+    const artists = await callBinding<{ ID: number; Name: string }[]>(
+      app,
+      'library.Library.GetArtists',
+      [0],
+    );
+    const first = artists[0]!;
+
+    await app.evaluate(
+      ([id, name]) => {
+        document.dispatchEvent(
+          new CustomEvent('navigate', {
+            detail: {
+              view: 'artist-details',
+              artistId: id,
+              artistName: name,
+            },
+            bubbles: true,
+            composed: true,
+          }),
+        );
+      },
+      [first.ID, first.Name] as const,
+    );
+
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'artist-details',
+    );
+    await expect(app.getByTestId('artist-play-all')).toBeEnabled();
+
+    const albums = await callBinding<{ ID: number }[]>(
+      app,
+      'library.Library.GetAlbumsByArtist',
+      [first.Name, 0],
+    );
+    const byAlbum = await callBinding<Record<string, string[]>>(
+      app,
+      'library.Library.GetFilePathsByAlbums',
+      [albums.map((a) => a.ID), 0],
+    );
+    const expected: string[] = [];
+
+    for (const album of albums) {
+      expected.push(...(byAlbum[String(album.ID)] ?? []));
+    }
+
+    await resetEvents(app);
+    await app.getByTestId('artist-play-all').click();
+    await waitForEvent(app, 'QueueChanged');
+
+    const state = await getQueue(app);
+
+    expect(state.tracks.map((t) => t.filePath)).toEqual(expected);
+    expect(state.source).toEqual({
+      type: 'artist',
+      id: first.ID,
+      label: first.Name,
+    });
+  });
+});

e2e/specs/playback.spec.ts

@@ -137,7 +137,7 @@ test.describe('queue', () => {
   });
 
   test('shuffle and repeat toggles report their state', async ({ app }) => {
-    const shuffle = app.getByRole('button', { name: 'Shuffle' });
+    const shuffle = app.getByRole('button', { name: 'Shuffle', exact: true });
 
     await resetEvents(app);
     await shuffle.click();

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

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

e2e/specs/queue-overlay.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '../support/fixtures.js';
+import { test, expect, openTheQueue } from '../support/fixtures.js';
 
 /**
  * #24 — the queue panel does not take the page's width away from it.
@@ -54,15 +54,15 @@ const shellGeometry = (page: import('@playwright/test').Page) =>
     };
   });
 
-async function openQueue(page: import('@playwright/test').Page) {
-  const toggle = page.locator('#queue-button');
-
-  if ((await toggle.getAttribute('aria-expanded')) !== 'true') {
-    await toggle.click();
-  }
-
-  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
-}
+/**
+ * Opening the queue is `openTheQueue`, which takes the route this
+ * viewport offers. It used to be a local helper that clicked
+ * `#queue-button` unconditionally, and #59 hid that button below
+ * 600px -- so the two phone bands here failed on a build where the
+ * queue was working perfectly, having been asserting *how* it opens as
+ * much as what it does.
+ */
+const openQueue = openTheQueue;
 
 test.describe('an open queue leaves the content its width', () => {
   for (const band of BANDS) {
@@ -157,6 +157,62 @@ test.describe('an overlaid queue says it is over the content', () => {
   });
 });
 
+/**
+ * #170 — the other two buttons in that same row.
+ *
+ * Clear queue and Add queue to playlist predate the close button and
+ * were named by a `title` attribute and nothing else. Unlike the
+ * sliders in `control-names.spec.ts`, that is not a *missing* name:
+ * `title` is the last fallback in the accname order, so
+ * `getByRole('button', { name: 'Clear queue' })` matched them before
+ * this fix as well as after it — measured, 1 and 1. A sweep for empty
+ * names cannot see a weak one, which is `a11y.26`'s complaint and the
+ * reason this file could have grown a green test that proved nothing.
+ *
+ * So the name is asserted twice, and the second assertion is the one
+ * that fails on the broken build. Taking the tooltip away and asking
+ * again is the property in words: **the name is not the tooltip**. It
+ * is what makes the button survive content being put inside it later,
+ * and it is the only one of the two a phone has — there is no hover on
+ * the surface #55 turned into a full screen. Measured on `main` before
+ * the fix: 0 and 0.
+ *
+ * Both buttons are disabled here, because the queue starts empty and
+ * naming is not enablement. A disabled button is still in the
+ * accessibility tree, which is exactly where the complaint was.
+ */
+test.describe('the queue header says what its actions do', () => {
+  const ACTIONS = ['Clear queue', 'Add queue to playlist'];
+
+  test('names both of the older actions', async ({ app }) => {
+    await openQueue(app);
+
+    for (const name of ACTIONS) {
+      await expect(
+        app.getByRole('button', { name, exact: true }),
+      ).toHaveCount(1);
+    }
+  });
+
+  test('and the names do not come from the tooltip', async ({ app }) => {
+    await openQueue(app);
+
+    await app.locator('#queue-panel').evaluate((el) => {
+      for (const button of el.shadowRoot!.querySelectorAll(
+        '.header-action-button',
+      )) {
+        button.removeAttribute('title');
+      }
+    });
+
+    for (const name of ACTIONS) {
+      await expect(
+        app.getByRole('button', { name, exact: true }),
+      ).toHaveCount(1);
+    }
+  });
+});
+
 /**
  * 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

e2e/specs/queue-selection.spec.ts

@@ -103,12 +103,17 @@ async function queueSixAndOpen(app: Page): Promise<void> {
      *
      * `explore-link` routes a track name to its *album's* page, so a
      * track with no album renders a name that navigates nowhere — and
-     * the fixture library deliberately contains two (`01 Tone A`,
-     * `02 Tone B`). Which tracks arrive first is `audio_files.id`
-     * order, i.e. the order the **scan** inserted them, which depends
-     * on concurrency and directory traversal: locally the first eight
-     * all had albums and the spec passed twice over, and CI rebuilds
-     * its seed with a real scan and got a different eight.
+     * the fixture library deliberately contains two,
+     * `unsorted/no-tags-at-all.mp3` and `unsorted/title-only.mp3`.
+     * (It contained four until #104: the two WAVs under `Field
+     * Recordings/Test Tones` had been tagged on disk all along and
+     * scan in with their album now, so they are ordinary tracks and
+     * not examples of this.) Which tracks arrive first is
+     * `audio_files.id` order, i.e. the order the **scan** inserted
+     * them, which depends on concurrency and directory traversal:
+     * locally the first eight all had albums and the spec passed twice
+     * over, and CI rebuilds its seed with a real scan and got a
+     * different eight.
      *
      * Asking for what the test needs is the fix. It is not a
      * narrowing: every assertion here wants an ordinary track, and

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

@@ -26,10 +26,22 @@ type Page = import('@playwright/test').Page;
  * 600 is the bottom of the Compact band (#24) and where the defect
  * lands; 899 and 900 straddle `nav-history` appearing (68px more to
  * find, at the width that just gained the sidebar's labels); 800 is the
- * enforced minimum; 390 is a phone, where the answer must be that
- * nothing collapses because the media queries already did the work.
+ * enforced minimum.
+ *
+ * **390 is kept, and what it asks changed with #57.** There is no bar
+ * to fit below 600px any more — it is out of the grid and visually
+ * hidden — so "nothing hangs out of it" is a claim about an element
+ * with no row, and would pass on a build that had merely broken the
+ * bar. Dropping the width would be dropping the one place this file
+ * can still say something true about a phone, so it asserts the
+ * *stronger* property instead, below: the bar is out of the layout
+ * altogether, which is the thing #57 wanted and the thing that makes
+ * fitting moot.
  */
-const WIDTHS = [390, 600, 800, 899, 900, 1440];
+const WIDTHS = [600, 800, 899, 900, 1440];
+
+/** Where #57 leaves the bar, and where the desktop still has one. */
+const PHONE_WIDTH = 390;
 
 /**
  * A scan whose title is as long as a real one gets. The label is capped
@@ -90,6 +102,56 @@ const collapsed = (page: Page) =>
   }));
 
 test.describe('the top bar fits the window', () => {
+  /**
+   * The phone's answer, which is not "it fits" (#57).
+   *
+   * The bar has no grid row below 600px, so measuring its children
+   * against its content box is measuring a 1px box that is already
+   * invisible — a fit pass would collapse the wordmark every time and
+   * report success about nothing, which is why `measureTopBarFit`
+   * declines to run at all when the bar is out of flow. What is worth
+   * asserting here is that the fit pass has not quietly started
+   * *undoing* that: a rule that put the bar back in the layout would
+   * pass every assertion in this file and cost a 439px screen 12% of
+   * its height.
+   */
+  test(`the bar is out of the layout at ${PHONE_WIDTH}px, with a job running`, async ({
+    app,
+    testctl,
+  }) => {
+    await app.setViewportSize({ width: PHONE_WIDTH, height: 600 });
+    await testctl.emit('JobsChanged', [LONG_JOB]);
+
+    // Not merely hidden: `display: none` on the header would satisfy
+    // "invisible" and leave the 3.25em row exactly where it was. So
+    // the assertion is that the content starts where the row above it
+    // ends -- and with a job staged, the row above it is the jobs
+    // band, which is the whole reason this row could go.
+    await expect
+      .poll(() =>
+        app.evaluate(() => {
+          const bar = document.querySelector<HTMLElement>('header.top-bar')!;
+          const main = document.querySelector<HTMLElement>('.main-panel')!;
+          const band = document.querySelector<HTMLElement>('job-band')!;
+
+          return {
+            position: getComputedStyle(bar).position,
+            gap:
+              Math.round(main.getBoundingClientRect().top) -
+              Math.round(band.getBoundingClientRect().bottom),
+          };
+        }),
+      )
+      .toEqual({ position: 'absolute', gap: 0 });
+
+    // And the work is still visible, in the band that replaced the
+    // indicator (#62) — which is what made this row removable at all.
+    await expect(app.locator('job-indicator')).toBeHidden();
+    await expect(app.locator('job-band').locator('job-row')).toHaveCount(1);
+
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
   for (const width of WIDTHS) {
     test(`no control sits outside the bar at ${width}px, idle`, async ({
       app,

e2e/specs/touch-gestures.spec.ts

@@ -0,0 +1,311 @@
+import { test, expect, callBinding } from '../support/fixtures.js';
+
+/**
+ * The touch gestures against the real app (plan 019, #63; long-press
+ * from plan 016 B2).
+ *
+ * The component tier proves the gestures in isolation, against markup
+ * it built itself. What it cannot prove is the half that made this one
+ * document listener instead of six: that the announced gesture reaches
+ * the handler a *real* component bound — `track-list` delegates on the
+ * `lit-virtualizer` rather than binding per row — and that the real
+ * menu opens from it, a path with its own history of opening and then
+ * refusing to work (see `menu-keyboard.spec.ts`).
+ *
+ * **Both halves of the reassignment are here, and the second is the
+ * one that matters.** #63 makes a hold on a *track row* mean selection
+ * mode; every other surface in the app keeps the context menu it has
+ * had, because an unclaimed `yj-long-press` still becomes a
+ * `contextmenu`. A spec that only checked the row would pass on a
+ * build that had silently broken the other thirteen menus.
+ *
+ * The pointer events are dispatched rather than performed: this
+ * project runs Desktop Chrome and Desktop Safari, neither of which has
+ * touch. So this is honest about what it checks — the app's own
+ * listeners, on the app's own DOM, from the events a touch would
+ * produce — and not about a real finger. The finger is the Android
+ * tier, and it found something this cannot see: Chrome 113's WebView
+ * fires its own `contextmenu` on a long press, which is why the module
+ * announces the gesture from a native event rather than standing down.
+ */
+
+/** A common small phone, as in `phone-shell.spec.ts`. */
+const PHONE = { width: 390, height: 844 };
+
+/** Comfortably past the module's 500ms hold. */
+const HELD = 900;
+
+type Page = import('@playwright/test').Page;
+
+/** A component's menu panel, or null while it is not rendered. */
+const panel = (page: Page, host: string) =>
+  page.evaluate((tag) => {
+    const el = document
+      .querySelector(tag)
+      ?.shadowRoot?.querySelector('.context-menu-panel');
+
+    if (!el) return null;
+
+    return {
+      role: el.getAttribute('role'),
+      label: el.getAttribute('aria-label'),
+      items: el.querySelectorAll('[role="menuitem"]').length,
+    };
+  }, host);
+
+/** How many tracks the selection bar says are selected, or null. */
+const selectionCount = (page: Page) =>
+  page.evaluate(() => {
+    const bar = document
+      .querySelector('track-list')
+      ?.shadowRoot?.querySelector('selection-bar');
+
+    return bar ? (bar as unknown as { count: number }).count : null;
+  });
+
+/**
+ * Press an element, optionally dragging partway through — the shape of
+ * a scroll that begins on a row, which must be neither gesture — and
+ * optionally lifting, which is what makes it a tap rather than a hold.
+ */
+async function press(
+  page: Page,
+  selector: { host: string; inner: string },
+  opts: { driftY?: number; lift?: boolean } = {},
+): Promise<void> {
+  await page.evaluate(
+    ({ host, inner, drift, lift }) => {
+      const el = document
+        .querySelector(host)
+        ?.shadowRoot?.querySelector(inner);
+
+      if (!el) throw new Error(`no ${inner} in ${host} to press`);
+
+      const box = el.getBoundingClientRect();
+      const x = Math.round(box.left + box.width / 2);
+      const y = Math.round(box.top + box.height / 2);
+      const send = (type: string, dy = 0) =>
+        el.dispatchEvent(
+          new PointerEvent(type, {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            pointerType: 'touch',
+            isPrimary: true,
+            clientX: x,
+            clientY: y + dy,
+          }),
+        );
+
+      send('pointerdown');
+
+      if (drift) send('pointermove', drift);
+      if (lift) send('pointerup');
+    },
+    {
+      host: selector.host,
+      inner: selector.inner,
+      drift: opts.driftY ?? 0,
+      lift: opts.lift ?? false,
+    },
+  );
+}
+
+// `.track-row`, not `[role="row"]`: the column header is a row too, and
+// it is the *first* one — a press on it is correctly ignored, which
+// reads exactly like the gesture not working.
+const TRACK_ROW = { host: 'track-list', inner: '.track-row' };
+
+test.describe('a hold on a track row selects it', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(PHONE);
+    await app.getByTestId('tab-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+  });
+
+  test.afterEach(async ({ app }) => {
+    // Every other spec file runs against a desktop, and the viewport
+    // belongs to the shared context rather than to this file.
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  test('raises the selection bar rather than the context menu', async ({
+    app,
+  }) => {
+    await expect.poll(() => selectionCount(app)).toBeNull();
+
+    await press(app, TRACK_ROW);
+
+    await expect
+      .poll(() => selectionCount(app), { timeout: HELD + 2000 })
+      .toBe(1);
+
+    // The gesture is claimed, so the menu this hold used to open must
+    // not also be up -- on a phone that would be a sheet over the bar.
+    expect(await panel(app, 'track-list')).toBeNull();
+  });
+
+  test('is neither gesture when the press turns into a scroll', async ({
+    app,
+  }) => {
+    await press(app, TRACK_ROW, { driftY: 40 });
+    await app.waitForTimeout(HELD);
+
+    expect(await selectionCount(app)).toBeNull();
+    expect(await panel(app, 'track-list')).toBeNull();
+  });
+});
+
+test.describe('a hold anywhere else still opens the menu', () => {
+  test.beforeEach(async ({ app }) => {
+    await app.setViewportSize(PHONE);
+    await app.getByTestId('tab-albums').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'albums',
+    );
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  test('reaches the delegated handler and opens the real menu', async ({
+    app,
+  }) => {
+    // The property that let #63 reassign the hold without touching one
+    // of the fourteen context menus: unclaimed, it is what it was.
+    // Without this half, breaking all of them passes the suite.
+    await expect.poll(() => panel(app, 'cover-grid')).toBeNull();
+
+    await press(app, { host: 'cover-grid', inner: '[role="option"]' });
+
+    await expect
+      .poll(() => panel(app, 'cover-grid'), { timeout: HELD + 2000 })
+      .toMatchObject({ role: 'menu' });
+
+    // The same panel Shift+F10 opens, items and all -- not an empty
+    // popup that happened to become visible.
+    expect((await panel(app, 'cover-grid'))?.items).toBeGreaterThan(0);
+  });
+});
+
+/**
+ * Swipe right on a track row to queue it (plan 019 phase 2, #63).
+ *
+ * The component tier has the rule this obeys — one row is a position,
+ * several are a choice — against a queue that is a fake. What is only
+ * true here is that the gesture reaches the *real* queue: `AddTracks`
+ * is a Go method, the queue is persisted, and "the row was added"
+ * is a question only the backend can answer.
+ *
+ * **It is Chromium-only, and that is a property of the browser rather
+ * than a gap.** The gesture runs on touch events, because Chrome 113's
+ * WebView cancels the pointer stream ~16px into any drag whatever
+ * `touch-action` says. Desktop WebKit implements no `TouchEvent`
+ * constructor at all — touch events are a mobile-Safari surface — so
+ * the events this needs cannot be built there. Skipping loudly is
+ * better than a spec that quietly asserts nothing on half the matrix,
+ * which is what `layout-overflow.spec.ts` and `back-navigation.spec.ts`
+ * were each doing when they were green on a broken build.
+ */
+test.describe('a swipe right on a track row queues it', () => {
+  test.beforeEach(async ({ app, browserName }) => {
+    test.skip(
+      browserName !== 'chromium',
+      'desktop WebKit has no TouchEvent constructor to build the gesture from',
+    );
+
+    await app.setViewportSize(PHONE);
+    await app.getByTestId('tab-tracks').click();
+    await expect(app.getByTestId('main-content')).toHaveAttribute(
+      'data-active-view',
+      'tracks',
+    );
+  });
+
+  test.afterEach(async ({ app }) => {
+    await app.setViewportSize({ width: 1440, height: 900 });
+  });
+
+  /**
+   * Drag the first row sideways by a fraction of its own width and
+   * lift. `fraction` is against the row, because the commit threshold
+   * is — a number of pixels here would be a second declaration of it,
+   * right on one viewport and wrong on the next.
+   */
+  const swipeFirstRow = (page: Page, fraction: number) =>
+    page.evaluate((f) => {
+      const row = document
+        .querySelector('track-list')
+        ?.shadowRoot?.querySelector('.track-row');
+
+      if (!row) throw new Error('no track row to swipe');
+
+      const box = row.getBoundingClientRect();
+      const y = box.top + box.height / 2;
+      const at = (x: number) =>
+        new Touch({
+          identifier: 1,
+          target: row,
+          clientX: box.left + x,
+          clientY: y,
+        });
+      const send = (type: string, points: Touch[]) =>
+        row.dispatchEvent(
+          new TouchEvent(type, {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            touches: points,
+            changedTouches: points.length > 0 ? points : [at(0)],
+          }),
+        );
+
+      send('touchstart', [at(0)]);
+
+      for (const step of [0.25, 0.5, 0.75, 1]) {
+        send('touchmove', [at(box.width * f * step)]);
+      }
+
+      send('touchend', []);
+    }, fraction);
+
+  /** How many tracks the backend says are in the queue. */
+  const queueLength = async (page: Page) => {
+    const state = await callBinding<{ tracks: unknown[] }>(
+      page,
+      'queue.Queue.GetState',
+    );
+
+    return state.tracks?.length ?? 0;
+  };
+
+  test('adds exactly one track to the real queue', async ({ app }) => {
+    const before = await queueLength(app);
+
+    await swipeFirstRow(app, 0.6);
+
+    await expect.poll(() => queueLength(app)).toBe(before + 1);
+
+    // Queued, not played: a swipe is not a tap, and the difference is
+    // what is on screen afterwards.
+    expect(
+      await app.getByTestId('main-content').getAttribute('data-active-view'),
+    ).toBe('tracks');
+  });
+
+  test('does nothing when the finger did not get far enough', async ({
+    app,
+  }) => {
+    const before = await queueLength(app);
+
+    await swipeFirstRow(app, 0.1);
+    await app.waitForTimeout(400);
+
+    expect(await queueLength(app)).toBe(before);
+  });
+});

e2e/support/fixtures.ts

@@ -140,6 +140,50 @@ export async function navigateTo(page: Page, view: string): Promise<void> {
     .waitFor({ state: 'attached' });
 }
 
+/**
+ * Open the queue the way a user at this viewport would.
+ *
+ * **The route differs by width and that is the feature, not an
+ * inconvenience.** Above 600px the bottom bar carries a queue button.
+ * Below it that button is gone (#59) and the queue is reached from the
+ * full-screen Now Playing view, which the mini player's art opens —
+ * "reachable only from Now Playing", which is what the issue asks for.
+ *
+ * It is here rather than in one spec because four files need it, and
+ * because a spec that hard-codes `#queue-button` is quietly asserting
+ * *which* route exists as well as what the queue does. Four of them
+ * were, which is how hiding one button failed ten tests about
+ * something else.
+ *
+ * The width is read from the page rather than passed, so a caller that
+ * resizes and then opens does not have to say so twice.
+ */
+export async function openTheQueue(page: Page): Promise<void> {
+  const toggle = page.locator('#queue-button');
+
+  if (await toggle.isVisible()) {
+    if ((await toggle.getAttribute('aria-expanded')) !== 'true') {
+      await toggle.click();
+    }
+
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    return;
+  }
+
+  // The phone: through Now Playing. `open-now-playing` is the mini
+  // player's art, which is a button only below 600px.
+  if (
+    (await page.getByTestId('main-content').getAttribute('data-active-view')) !==
+    'now-playing'
+  ) {
+    await page.getByTestId('open-now-playing').click();
+  }
+
+  await page.getByTestId('npv-queue').click();
+  await expect(page.locator('#queue-panel')).toHaveAttribute('open', '');
+}
+
 /** Thin client for the dev-only /__test/ surface (backend/testctl). */
 export class TestCtl {
   constructor(private readonly baseURL: string) {}

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

@@ -69,6 +69,14 @@ export function GetPinDefaultPlaylist(): $CancellablePromise<boolean> {
     return $Call.ByID(3818283301);
 }
 
+/**
+ * GetPopupVolume reports whether the bottom bar's volume control is a
+ * click-to-open popup rather than an inline slider (#42).
+ */
+export function GetPopupVolume(): $CancellablePromise<boolean> {
+    return $Call.ByID(2885777);
+}
+
 /**
  * GetQueueFallback returns what plays, if anything, once the queue
  * runs out.
@@ -207,6 +215,18 @@ export function SetPinDefaultPlaylist(pin: boolean): $CancellablePromise<void> {
     return $Call.ByID(372446849, pin);
 }
 
+/**
+ * SetPopupVolume saves the volume control's presentation.
+ * 
+ * Nothing to validate: both values are legal at every width, and the
+ * frontend additionally stands the inline slider down below the phone
+ * breakpoint whatever this says, because that is about room rather than
+ * about preference.
+ */
+export function SetPopupVolume(popup: boolean): $CancellablePromise<void> {
+    return $Call.ByID(1430308453, popup);
+}
+
 /**
  * SetQueueFallback validates and saves a new queue-fallback mode.
  */