# UI/UX audit — YellowJacket

Date: 2026-08-11. Method: the app driven by hand headlessly
(`make dev-headless SEED=default` + `playwright-cli`, then
`make dev-headless-fresh` for first run), plus three read-only static
reviews. Nothing was changed.

- `hands-on.md` (this file) — the empirically confirmed findings, i.e.
  things observed happening in the running app, with the reproduction.
- `a11y.md` — accessibility and interaction model.
- `perf.md` — rendering performance, memory, state correctness.
- `errors.md` — error handling, empty/loading states, destructive actions.

Findings below are numbered `H-n` (hands-on) and cross-reference the
static reports where they overlap. The reconciliation plan built from
all four files is `.planning/plans/completed/007-ui-reconciliation.md`.

---

## Critical — confirmed by reproduction

### H-1. A keypress on any page silently mutates the Autotag queue

Every view the user visits stays mounted forever (`index.ts`, class
`view-hidden`), so `disconnectedCallback` never runs and
`autotag-view`'s `document` keydown listener (`autotag-view.ts:1188`,
handler at `:1706`) stays live for the rest of the session.

Reproduced: visited Autotag (Pending 11), navigated to Settings,
dispatched `keydown` `s` twice → **Pending 9**. Two albums skipped from
a page that was not on screen and gave no feedback. `a` on the same
listener is Apply, which rewrites tags on disk.

### H-2. `s` and the arrow keys fire two handlers at once

`autotag-view`'s listener and `keyboard-shortcut-service` are both on
`document` and neither defers. Reproduced on the Autotag page: pressing
`s` emitted `QueueModeChanged` (shuffle toggled) *and* skipped the
album. `ArrowUp`/`ArrowDown` navigate the folder list *and* change the
volume by 5, so walking the autotag list with the keyboard ramps volume
to 0 or 100.

### H-3. The progress bar is a local timer that lies, and a keyboard seek desyncs it by ~30 s

`seek-bar.ts:110-116` increments `seekValue` by 1 every 1000 ms and only
resyncs when `trackChangeId` changes. Nothing reconciles it against
`Player.CurrentPositionSeconds`.

Reproduced twice:

| | UI | backend |
|---|---|---|
| steady playback, +10 s | 00:47 → 00:57 | 50 → 60 (constant 3 s lie) |
| after 4× `ArrowRight` (seek +5 s) | 00:08 → **00:10** | 11 → **40** |

The keyboard seek path (`keyboard-shortcut-service.ts:207-214`) calls
`Player.Seek` and never tells the seek bar, so the bar does not move at
all — the shortcut looks broken, and the displayed time is wrong for
the rest of the track.

### H-4. Every icon in the app is fetched from fontawesome.com at runtime

Confirmed from `performance.getEntriesByType('resource')`:
`https://ka-f.fontawesome.com/releases/v7.1.0/svgs/solid/house.svg`
and 35 more. `setBasePath('/dist/webawesome')` in `index.ts` does not
affect the icon resolver, and no `registerIconLibrary` call exists.
A desktop music player offline, on a captive portal, or behind a
firewall renders **no icons at all**. See `perf.md` M9.

### H-5. The whole app is unusable without a mouse

Tabbing through the entire app yields **14 stops**, all of them chrome
(library filter, search, one unlabelled track-list button, two queue
buttons, five transport buttons, volume, queue toggle, seek). The
sidebar nav (`app-sidebar.ts:202`, bare `<li @click>`), every track
row, every album/artist/genre card and every context menu are
unreachable. `Enter` on a selected track does nothing — reproduced.

The cause of the last part is that `data-shortcut-scope` is **never set
anywhere in the codebase**, so `resolveScope` can only return
`text-input` or `global`, and the two panel-scoped bindings
(`tracklist.play` = Enter, `tracklist.delete` = Delete) are dead
shortcuts that the Settings page still advertises as configurable.

Related: the closed queue panel is `width: 0` but not `inert` and not
`visibility: hidden` (`queue-panel.ts:214`), so its Clear/Add buttons
still take tab stops and are read by screen readers — reproduced, they
appear in the tab order at x=1440.

---

## Major — confirmed by reproduction

### H-6. Global single-key shortcuts hijack keys from focused controls

Defaults (`backend/shortcuts/shortcuts.go:16`) bind unmodified
`Space N P S R M / Q ↑ ↓ ← →` at global scope, and the service calls
`preventDefault()` on a match. Only text inputs are exempt. So a
focused `<button>` cannot be activated with Space, the native
`<select>` library filter cannot be arrowed through, the volume and
seek sliders fight the global handler for arrow keys, and Space/arrow
page scrolling is dead everywhere.

`ArrowUp` also emits `MuteChanged` alongside `VolumeChanged` even when
nothing is muted — reproduced.

### H-7. The last column of the track list is always clipped by exactly 40 px

`computeDefaultWidths` (`track-list.ts:409`) distributes
`this.clientWidth` across the columns but never subtracts the 24 px
favourite column or the 2×8 px row padding that
`colBoundaryPositions` (`:378`) knows about. Measured: every
`.track-row` and the `.header-row` report `scrollWidth 1280` against
`clientWidth 1240`. Duration renders as "Durat…" on a fresh profile at
1440×900, and disappears entirely below ~1000 px.

### H-8. The app never lands on Home

`app-sidebar.ts:124` defaults `activeView = 'tracks'`. The curated Home
page — the one with the "somewhere to start listening" shelves — is
listed first in the nav and is never what the user sees on launch.

### H-9. On the Home page, an album with no cover art renders as nothing

The Home shelf card's missing-art placeholder has no background, so the
tile is invisible against the page and the shelf reads as having holes
in it. The Albums grid and the Artists grid both do this correctly
(letter-on-a-tile), so this is one card renderer disagreeing with the
other two.

Also on Home: with a small library all three shelves ("Fresh in your
library", "Never played", "Take a chance") show the **same seven
albums** in different orders, so the page reads as repeating itself.
A shelf whose contents largely duplicate the shelf above it would be
better suppressed, the way an empty one already is.

### H-10. The header search is view-scoped but looks global

Typing `tide` on the Playlists page produced **"No playlists match your
search"** while three tracks named *Tideline* sat in the library. The
box is in the global header, is placeheld "Search…", and persists its
term across navigation, so it reads as a library-wide search and is
not one. It also vanishes entirely on Home and Explore (Explore has its
own second search box), and its appearing/disappearing shifts the whole
header layout.

### H-11. The layout has no responsive behaviour and the enforced minimum window is too small

`MinWidth/MinHeight` are 512×384 (`backend/config/window.go:15`). At
900×600 the Duration column is off-screen; at 700×480 the sidebar
overflows behind the player bar with no scroll, so **Settings and Jobs
become unreachable**, and the app title wraps into the nav. The sidebar
has a `.collapsed` icon mode but nothing triggers it automatically.

### H-12. First run shows "Loading tracks…" behind an inert copy of the whole app

On an empty `YJ_HOME` the wizard is a modal over a fully rendered app —
sidebar, transport, search, library filter all visible and all inert —
with a permanent "Loading tracks…" in the content area (the track list
cannot tell empty from loading, `track-list.ts:1901`). Meanwhile the
"Building search index" job is already downloading a 1.1 M-row catalog
before the user has chosen a folder or consented to it.

`Get Started` is correctly disabled until a folder is chosen, but it is
the filled accent button and its disabled state is barely visible.

### H-13. The album detail page has no way to play the album

The primary action is missing: no Play, no Shuffle, no Add to queue on
the album header. Nor is there any legend for the green ✓ badges shown
against the album title and every track.

### H-14. `IndexStatusChanged` is emitted every 3 seconds forever

`searchindex.go:276` starts an unconditional 3 s ticker in
`SetContext` and never stops it. The payload is byte-identical once the
index is ready (`building:false, ready:true`) and it keeps firing for
the life of the process. Each tick re-renders the 2 149-line
`config-page` (which never unmounts) and writes a `console.log`
(`config-page.ts:1019`) — the browser console filled with ~200
identical lines during a 20-minute session. See `perf.md` M6.

---

## Minor — confirmed by observation

- **H-15.** Three identical `Tideline / Aurora Fields / 00:06` rows are
  indistinguishable in the track list; the default columns carry no
  album, format or path, so the app's own duplicate fixtures cannot be
  told apart by eye in a library manager that has a duplicate-detection
  feature.
- **H-16.** The remaining-time label is a countdown with no minus sign,
  no label and no toggle to total duration — `01:21` next to a track
  the list says is `01:30`.
- **H-17.** The now-playing artist is truncated to a fixed ~120 px
  ("The Orchestra Of") while ~400 px of empty space sits between it and
  the transport controls.
- **H-18.** When a queue finishes, the now-playing bar empties
  completely, losing the context of what just played, while the queue
  panel still lists the finished track.
- **H-19.** Page headings are inconsistent: Playlists, Downloads, Jobs,
  Settings and Home have a title (and Playlists/Downloads/Jobs have
  header actions); Artists, Genres, Albums and Tracks have none, and
  none of them shows a count. Sort controls exist on Albums and Tracks
  but not on Artists or Genres.
- **H-20.** The sidebar's hover colour (`#343a40`) and its active
  colour (`#495057`) are close enough that a hovered item reads as a
  second selected item.
- **H-21.** The track context menu has no Escape handler, no keyboard
  navigation and no focus movement (`context-menu-controller.ts` binds
  only click/contextmenu/mousedown), and is missing the conventional
  entries: Go to album, Go to artist, Show in file manager, Edit tags,
  Remove from library.
- **H-22.** In Settings, "Libraries" — the section that matters most —
  is last and below the fold, while "Search Index" is first and
  expanded by default. There is no Playback/Audio section at all (no
  output device, gapless, crossfade or replay gain).
- **H-23.** Explore is an empty page with a search box over a 1.1 M-row
  catalog: no browse, no popular-artists entry point, nothing to do
  without typing.
- **H-24.** Long body copy (Downloads' intro, Jobs' descriptions) runs
  the full ~1200 px content width with no measure cap.

---

## Where the bar is already high

Worth naming, because the findings above are the exceptions:

- **`downloads-view`** — the best empty state in the app: it says what
  the feature is, why nothing is happening, and exactly what to do next.
- **`autotag-view`** — genuinely dense and legible: per-field match
  breakdown, your-folder-vs-candidate side by side, confidence stated
  rather than hidden.
- **`jobs-view`** — running / libraries / maintenance / recently
  finished, with the destructive action visually separated and honestly
  described.
- **`track-list`** — a properly built virtualized list (memoized
  filter/sort, delegated handlers, `_itemSize` hint, inline SVG for the
  per-row icon). Its problems are at the edges, not in the core.
- **`player-controls`** — every button labelled, `aria-pressed` on the
  toggles, repeat's three-state mode spelled into the label.

---

## Suggested order

1. **H-1 / H-2** — a hidden page mutating files on a keystroke is the
   only finding here that loses user data. Fix the view lifecycle
   (deactivate hidden views) and make the two keydown listeners agree.
2. **H-3** — drive the seek bar from the backend position; the core
   surface of a music player currently lies.
3. **H-4** — bundle the icons; the app is not usable offline.
4. `errors.md` **C1** — a track that fails to play is a silent no-op,
   which is the same class of problem as H-3 on the same surface.
5. **H-5 / H-6** — keyboard access, and stop the global shortcuts
   stealing keys from focused controls.
6. **H-7 / H-11** — the layout arithmetic and a real minimum size.
7. Then the consistency pass: **H-8, H-9, H-10, H-13, H-19**.