minstrel/docs/superpowers/specs/2026-05-03-m7-track-actions-menu-design.md

M7 — Track-level actions menu

Status: Draft for review · 2026-05-03

Phase: M7 task #372. Web-side polish slice. Replaces the single-entry <TrackMenu> (built as scaffolding for M5b's quarantine flag) with a real per-track action set. Lands before M7 #352 (Playlists CRUD) so the "Add to playlist…" entry has a menu to slot into. Mirrored on Flutter in a later slice once the web surface is settled.

1. Goal

Per-track kebab menu wherever <TrackRow> or the <PlayerBar> track display is used, exposing the full set of actions a user can take on a track right now: queue manipulation, library state changes (Like, Hide), navigation (Go to album/artist), Lidarr-aware track removal, and a placeholder slot for "Add to playlist…" that #352 fills.

2. Goals and non-goals

Goals

• <TrackMenu> exposes nine entries, grouped four ways:
  1. Queue: Play next · Add to queue
  2. Collection: Like / Unlike · Add to playlist… (slot reserved; wired by #352)
  3. Navigation: Go to album · Go to artist
  4. Lifecycle: Flag this track… · Hide / Unhide · Remove from library (admin-only)
• "Like / Unlike" and "Hide / Unhide" entries duplicate functionality already on the row (heart and eye icon buttons). Reason: keyboard discoverability — once the kebab is focused, arrow-keys reach every action; mouse users still get one-tap heart/eye on the row.
• "Add to playlist…" reserves the menu slot but the submenu of playlists is wired in #352, not here. The slot renders as disabled with a tooltip "Coming with playlists" until #352 ships.
• "Go to artist" is single-target (track.artistId); compilation/feature artists aren't modeled in the schema today and that's a schema problem to solve before this entry needs a submenu.
• "Remove from library" is admin-only — gated client-side by currentUser.is_admin, server-side by the existing auth.RequireAdmin() middleware on the new /api/admin/tracks/{id} route. New backend endpoint deletes the track row, removes the file from disk (or via Lidarr for Lidarr-managed tracks), and cascades album → artist tidy-up if either becomes empty.
• Keyboard accessibility: kebab is <button aria-haspopup="menu" aria-expanded>; opened menu has role="menu" with each entry role="menuitem". Up/Down arrows cycle, Enter activates, Escape closes and returns focus to the kebab.
• Error envelope: existing copyForCode() helper resolves all surface errors (lidarr_unreachable, lidarr_unauthorized, lidarr_server_error, not_found, unauthorized, connection_refused).

Non-goals (this slice)

• Per-track metadata editing (title / artist / track_number / genre / year / etc.) — filed as M7 #373 ("Track metadata editing"). Crosses into Lidarr's territory and the scanner's reconciliation logic; deserves its own spec.
• "Add to playlist…" submenu wiring — lands in #352 (Playlists CRUD slice 1).
• "Remove from library" exposed to non-admin users — admin-only matches the existing model (file management is an operator concern).
• Multi-artist disambiguation on "Go to artist" — schema doesn't model collaborator artists today; expanding the menu to a submenu earns its keep only after the schema does.
• Submenu UI infrastructure beyond the playlists hook — no other entries need submenus in this slice.
• Flutter mirror — separate task once web settles (#356 follow-up slice).

3. Architecture

Backend

One new admin endpoint: DELETE /api/admin/tracks/{id}. Handler in internal/api/admin_tracks.go (new file). Calls a new internal/tracks package that owns the removal logic.

internal/tracks/service.go exposes RemoveTrack(ctx, trackID, adminID) returning (deletedAlbumID *string, deletedArtistID *string, err). Steps:

1. Look up the track. Need: file_path, lidarr_managed, album_id, artist_id. Returns ErrNotFound if missing.
2. For Lidarr-managed tracks: call the existing Lidarr client to delete the track via Lidarr first. The current lidarrquarantine.DeleteViaLidarr handles this for quarantined tracks; the same primitive applies. If Lidarr is unreachable / unauthorized / errors, return the same typed errors (ErrLidarrUnreachable, ErrLidarrUnauthorized, ErrLidarrServerError) that the quarantine flow already maps. The DB row is NOT deleted on Lidarr failure — Lidarr would re-import on next sync and the row would come back inconsistent.
3. For non-Lidarr tracks: os.Remove(file_path). If the file is already missing, log slog.Warn("track delete: file already missing", "path", file_path, "track_id", id) and proceed — the goal is DB consistency.
4. Begin a single DB transaction:
   • DELETE FROM tracks WHERE id=$1. Existing FK ON DELETE CASCADE handles play_events, general_likes_tracks, lidarr_quarantine. (Future playlist_tracks will also need ON DELETE CASCADE — locked when #352's migration lands.)
   • Verify all relevant FKs are CASCADE: read internal/db/migrations/*.up.sql. If any are RESTRICT or have no FK rule, fix as part of this slice via migration 0014_track_cascades.up.sql — only if needed.
   • Count remaining tracks for the album. If 0, DELETE FROM albums WHERE id=$2. Set deletedAlbumID.
   • If album was deleted: count remaining albums for the artist. If 0, DELETE FROM artists WHERE id=$3. Set deletedArtistID.
   • Commit.
5. Return (deletedAlbumID, deletedArtistID, nil).

API handler maps the typed errors:

• ErrNotFound → 404 {"error": "not_found"}
• ErrLidarrUnreachable → 503 {"error": "lidarr_unreachable"}
• ErrLidarrUnauthorized → 503 {"error": "lidarr_unauthorized"}
• ErrLidarrServerError → 502 {"error": "lidarr_server_error"}
• success → 200 {"deleted_track_id": "...", "deleted_album_id": "...?", "deleted_artist_id": "...?"}

Frontend

<TrackMenu> is rewritten from "kebab → FlagPopover only" to "kebab → menu with grouped entries". The menu API stays compatible (same track: TrackRef and direction: 'up'|'down' props), so existing callers (<TrackRow>, <PlayerBar>) pick up the new entries with no code change.

Two new component primitives:

• <TrackMenuItem> — single row of the menu (<button role="menuitem"> + Lucide icon + label + optional shortcut indicator).
• <TrackMenuDivider> — <hr> styled to FabledSword's pewter/slate.

<TrackMenu>'s state machine:

• menuOpen: boolean — set true on kebab click; toggles aria-expanded.
• popoverOpen: boolean — set true when "Flag this track…" fires; menuOpen flips to false.
• Outside-click handler closes both.

Audio queue mutations are pure client-state. The existing audio store gets two methods:

function playNext(track: TrackRef) {
  // Splice immediately after the current index.
  _queue.splice(_index + 1, 0, track);
}

function addToQueue(track: TrackRef) {
  _queue.push(track);
}

Like / Unlike + Hide / Unhide reuse the existing likeTrack / unlikeTrack and quarantineTrack / unquarantineTrack API helpers + their TanStack Query invalidations.

"Remove from library" calls a new web/src/lib/api/admin/tracks.ts::removeTrack(id). On success, invalidate qk.albums(track.albumId), qk.artists(track.artistId), qk.home(), plus any list-page query keys currently rendered. The response payload's optional deleted_album_id / deleted_artist_id lets the client also evict those entity caches.

Navigation entries call goto('/albums/' + track.albumId) and goto('/artists/' + track.artistId) directly — no async, no error path.

Accessibility

• Kebab <button> carries aria-label="Track actions", aria-haspopup="menu", aria-expanded={menuOpen}.
• Open menu has role="menu". Each entry: <button role="menuitem">. Disabled entries (admin-only for non-admin users; "Add to playlist…" pre-#352) have aria-disabled="true" rather than being absent — keeps the menu height stable so muscle memory works for both user types.
• Up/Down arrow keys cycle focus through visible enabled items. Home/End jump to first/last. Escape closes and returns focus to the kebab. Enter activates the focused item.
• The submenu plumbing #352 lands will use arrow-right to enter, arrow-left to exit, with focus following.

4. File map

Backend — create

• internal/tracks/service.go — RemoveTrack(ctx, id, adminID) + typed errors.
• internal/tracks/service_test.go — unit tests covering the six service paths (Lidarr happy, non-Lidarr happy, file-already-gone, Lidarr error, album-empty cascade, artist-empty cascade).
• internal/api/admin_tracks.go — handleRemoveTrack(w, r).
• internal/api/admin_tracks_test.go — HTTP tests (admin-only auth, 4 error codes, response envelope).

Backend — modify

• internal/api/api.go — register admin.Delete("/tracks/{id}", h.handleRemoveTrack).
• internal/db/queries/tracks.sql — append DeleteTrack, DeleteAlbumIfEmpty, DeleteArtistIfEmpty, CountTracksByAlbum, CountAlbumsByArtist.
• internal/db/dbq/* — regenerated by sqlc generate.
• internal/db/migrations/0014_track_cascades.up.sql — conditional, only if any of play_events, general_likes_tracks, lidarr_quarantine lacks ON DELETE CASCADE on its track_id FK. Read existing migrations first; skip if all cascades are already correct.

Frontend — create

• web/src/lib/components/TrackMenuItem.svelte — single-entry primitive.
• web/src/lib/components/TrackMenuItem.test.ts
• web/src/lib/components/TrackMenuDivider.svelte — visual separator.
• web/src/lib/api/admin/tracks.ts — removeTrack(id).
• web/src/lib/api/admin/tracks.test.ts

Frontend — modify

• web/src/lib/components/TrackMenu.svelte — full rewrite from FlagPopover-only to multi-entry menu.
• web/src/lib/components/TrackMenu.test.ts — full rewrite.
• web/src/lib/components/TrackRow.svelte — no code change required (uses <TrackMenu>'s same prop API).
• web/src/lib/components/PlayerBar.svelte — no code change required.
• web/src/lib/components/TrackRow.test.ts — adjust expectations (menu now has 9 entries instead of 1).
• web/src/lib/components/PlayerBar.test.ts — same.
• web/src/lib/api/queries.ts — no new query keys. The Remove flow invalidates existing qk.albums(id) / qk.artists(id) / qk.home() plus any list-page keys currently rendered. There is no admin-tracks list view in this slice.
• web/src/lib/stores/audio.ts — add playNext(track) and addToQueue(track) methods.
• web/src/lib/stores/audio.test.ts — extend to cover the new methods.

5. API contract

DELETE /api/admin/tracks/{id}

Auth: admin session.

Request: no body.

Response (200 OK):

{
  "deleted_track_id": "uuid",
  "deleted_album_id": "uuid",
  "deleted_artist_id": "uuid"
}

deleted_album_id and deleted_artist_id are optional. Present only when removing the track left the parent empty and the row was deleted too.

Errors:

Status	Code	Trigger
401	unauthenticated	no session
403	unauthorized	non-admin session
404	not_found	track id doesn't exist
502	lidarr_server_error	Lidarr returned 5xx
503	lidarr_unreachable	network error reaching Lidarr
503	lidarr_unauthorized	Lidarr rejected the API key
500	server_error	unexpected error (DB, filesystem)

6. Error handling (frontend)

removeTrack(id) reuses apiFetch with the existing dual-envelope handling. Errors surface as a toast via copyForCode(code):

• lidarr_unreachable → "Lidarr is unreachable right now. Try again, or check Admin → Integrations." (existing copy)
• lidarr_unauthorized → existing copy
• lidarr_server_error → existing copy
• not_found → "Track no longer exists." Trigger refetch of parent list query.
• unauthorized → "Admins only." (Defensive — UI should hide the entry for non-admins.)
• connection_refused → existing copy.

Audio queue mutations have no error path — they are local state writes. Defensive guard: if _queue is null (audio store uninitialized), the action is a no-op.

7. Testing

Backend

• internal/tracks/service_test.go — unit tests, table-driven where it helps:
  • Non-Lidarr track happy path. File present, deletes cleanly. DB row gone. Album / artist persist.
  • Lidarr-managed track happy path. Lidarr returns 200; file removed by Lidarr; DB row gone.
  • File-already-missing path. os.Remove returns ErrNotExist. Service logs warning, proceeds. DB row gone.
  • Lidarr error propagation. lidarr_unreachable / lidarr_unauthorized / lidarr_server_error each surface as the matching Err…. DB row stays.
  • Album-empty cascade. Track was the album's only track. Album row deleted, artist persists if has other albums. deletedAlbumID returned.
  • Artist-empty cascade. Track was the artist's only track. Album AND artist deleted. Both IDs returned.
• internal/api/admin_tracks_test.go — HTTP tests:
  • Non-admin → 403 unauthorized.
  • No session → 401 unauthenticated.
  • Unknown id → 404 not_found.
  • Each typed Lidarr error → matching response code + envelope.
  • Happy path → 200 with deleted_track_id (and optionally deleted_album_id / deleted_artist_id).

Frontend

• TrackMenu.test.ts (rewrite) covers:
  • Each of the 9 entries renders for an admin user.
  • "Remove from library" is hidden for non-admin (or renders disabled with aria-disabled="true").
  • "Add to playlist…" renders disabled with the "Coming with playlists" tooltip.
  • Kebab aria-haspopup="menu", aria-expanded cycles on open/close.
  • Up/Down arrow keys cycle focus; Escape closes; Enter activates.
  • Outside click closes.
  • Submenu plumbing (role="menu" on the playlist hook) renders even though disabled.
• TrackMenuItem.test.ts — primitive renders icon, label, click handler fires, aria-disabled honored.
• tracks.test.ts (new admin API helper) — removeTrack posts the correct method+URL, parses success envelope, surfaces errors.
• audio.test.ts (extend) — playNext(track) splices at _index+1; addToQueue(track) appends; both no-op on empty queue.
• TrackRow.test.ts and PlayerBar.test.ts (adjust) — existing assertions about the menu's sole "Flag" entry need updating to match the new 9-entry structure. The compatible prop API means no other test changes needed.

8. Distribution / migration notes

• Migration 0014: conditional. Read the existing FKs from migrations 0002 (tracks), 0005 (play_events), 0006 (general_likes), 0011 (lidarr_quarantine). If any FK on track_id is RESTRICT or NO ACTION, write a migration to ALTER TABLE … DROP CONSTRAINT … ADD CONSTRAINT … ON DELETE CASCADE. If all four are already CASCADE, skip the migration entirely.
• No client breaking changes. The <TrackMenu> prop API is unchanged.
• min_client_version bump in internal/server/version.go: not required — the new endpoint only matters for admins, and the menu degrades gracefully on old clients (they don't show entries they don't know about).

9. Origin

M7 #372. Brainstorm 2026-05-03. Decisions locked:

1. Per-track metadata editing is out of scope — filed as M7 #373.
2. Menu structure: 9 entries in 4 groups. Like/Hide duplicated in menu for keyboard discoverability.
3. Go to artist single-target — multi-artist data model isn't there yet.
4. Remove from library admin-only, with cascade album → artist tidy-up.
5. Submenu plumbing only matters for #352's Add to playlist… and is reserved as a slot here.

10. Related

• M7 #352 — Playlists CRUD. Wires Add to playlist… submenu into the menu slot reserved here. Brainstorm parked at task-log id 44.
• M7 #373 — Track metadata editing. Split out from #372 in this brainstorm.
• M5b quarantine — <FlagPopover> and the quarantineTrack / unquarantineTrack helpers reused by the Hide/Unhide entries.
• M2 likes — likeTrack / unlikeTrack and the existing heart icon, now also surfaced as a menu entry.
• M5a Lidarr — Lidarr-aware delete reuses the same primitive lidarrquarantine.DeleteViaLidarr uses today.
• M7 #356 — Flutter mirror in a later slice once the web menu settles.