feat(a11y): give the context menu a keyboard, and the app a voice

The context menu was the only route to Play, Add to Queue, Play Next,
Add to Playlist, Favourite and Track Details, and it opened on
right-click alone: the panel had no role=menu, so its six menuitems were
orphaned, nothing moved focus into it, and nothing handled arrows or
Escape (a11y.3). Phase 1 deferred this deliberately so it would land
with the dialogs, as one focus-management implementation.

MenuKeyboard is that model. It is standalone rather than part of
ContextMenuController because playlist-view renders a menu without the
controller, and the only thing worse than a menu with no keyboard model
is two menus with two of them. Shift+F10 and the ContextMenu key open it
from a focused row, anchored to that row, and focus returns there.

Three lists had no focused row to open it from, so they gained a roving
tab stop (utils/roving-rows.ts, written once rather than three times).
track-list keeps its own: it predates this, carries selection semantics
the other three do not have, and is pinned by its own tests.

Also the ARIA tail this is one story with: aria-sort on the column
headers (role=columnheader arrived in Phase 1 without it), listbox and
option on the four selectable grids — aria-selected on role=button is
invalid and was being dropped, so the state the whole ctrl/shift
interaction exists to produce was invisible — and live regions on the
four async surfaces that changed in silence.

Two things a reproduction taught that reading could not: the
wa-dropdown-items have not set their role when the host's updateComplete
resolves, so querying by role then finds nothing and the menu opens
without taking focus; and focus() on a popup that has not positioned
itself is a silent no-op.

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

@@ -24,6 +24,7 @@ import { queueStore } from '@store/queue-store';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
@@ -948,6 +949,23 @@ export class ArtistsView
         );
     };
 
+    /** Shift+F10 / ContextMenu on a focused card, anchored to the card
+     *  so the menu appears where the artist is and focus goes back
+     *  there when it closes. */
+    private openArtistMenuFromKey(
+        e: KeyboardEvent,
+        artist: library.Artist,
+    ): void {
+        const card = e.currentTarget as HTMLElement | null;
+
+        if (!card) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+        this.contextMenuArtistId = artist.ID;
+        this.ctxMenu.openFrom(card);
+    }
+
     private async onContextMenuAction(
         action: string,
     ) {
@@ -1193,7 +1211,7 @@ export class ArtistsView
                 data-index=${index}
                 tabindex=${this.roving.tabIndexFor(index)}
                 @focus=${() => this.roving.noteFocus(index)}
-                role="button"
+                role="option"
                 aria-label="${artist.Name}"
                 aria-selected="${isSelected}"
                 style="
@@ -1212,6 +1230,15 @@ export class ArtistsView
                         artist,
                     )}
                 @keydown=${(e: KeyboardEvent) => {
+                    if (isContextMenuKey(e)) {
+                        this.openArtistMenuFromKey(
+                            e,
+                            artist,
+                        );
+
+                        return;
+                    }
+
                     if (
                         e.key === 'Enter' ||
                         e.key === ' '
@@ -1266,6 +1293,8 @@ export class ArtistsView
                     ? html`
                           <div
                               class="context-menu-panel"
+                              role="menu"
+                              aria-label="Artist actions"
                           >
                               <wa-dropdown-item
                                   @click=${() =>
@@ -1442,6 +1471,9 @@ export class ArtistsView
                 @keydown=${this.roving.handleKeydown}
             >
                 <lit-virtualizer
+                    role="listbox"
+                    aria-label="Artists"
+                    aria-multiselectable="true"
                     .items=${entries}
                     .renderItem=${(entry: ArtistEntry) => this.renderArtistCard(entry)}
                     .keyFunction=${(entry: ArtistEntry) => entry.artist.ID}

frontend/src/components/cover-grid/cover-grid.ts

@@ -46,7 +46,10 @@ import {
     emitDragActive,
 } from '@utils/drag-controller';
 import type { DragPayload } from '@utils/drag-controller';
-import { ContextMenuController } from '@utils/context-menu-controller.js';
+import {
+    ContextMenuController,
+    isContextMenuKey,
+} from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { artistLink, exploreLinkStyles } from '../../utils/explore-link';
@@ -1050,6 +1053,26 @@ export class CoverGrid
     private onGridAlbumKeydown = (
         e: KeyboardEvent,
     ) => {
+        if (isContextMenuKey(e)) {
+            const target = this.resolveAlbumFromEvent(e);
+            const card =
+                e.composedPath().find(
+                    (el): el is HTMLElement =>
+                        el instanceof HTMLElement &&
+                        el.classList.contains('album-card'),
+                );
+
+            if (!target || !card) return;
+
+            e.preventDefault();
+            e.stopPropagation();
+            this.contextMenuAlbumId = target.album.ID;
+            this.contextMenuTarget = { kind: 'album' };
+            this.ctxMenu.openFrom(card);
+
+            return;
+        }
+
         if (e.key !== 'Enter' && e.key !== ' ') return;
 
         const hit = this.resolveAlbumFromEvent(e);
@@ -1679,7 +1702,8 @@ export class CoverGrid
                 class=${classes}
                 tabindex=${this.roving.tabIndexFor(index)}
                 @focus=${() => this.roving.noteFocus(index)}
-                role="button"
+                role="option"
+                aria-selected=${this.selectedAlbums.has(album.ID)}
                 data-index=${index}
                 aria-label="${album.Name} by ${album.ArtistName}"
                 draggable="true"
@@ -1780,6 +1804,9 @@ export class CoverGrid
         return html`
             <lit-virtualizer
                 id="grid-single"
+                role="listbox"
+                aria-label="Albums"
+                aria-multiselectable="true"
                 .items=${this.buildGridEntries()}
                 .renderItem=${this.renderGridEntry}
                 .keyFunction=${(entry: GridEntry) => entry.album.ID}
@@ -1877,7 +1904,7 @@ export class CoverGrid
             >
                 ${ctxMenu.contextMenuOpen
                 ? html`
-                          <div class="context-menu-panel">
+                          <div class="context-menu-panel" role="menu" aria-label="Album actions">
                               <wa-dropdown-item
                                   @click=${() =>
                         this.onContextMenuAction(

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

@@ -2,6 +2,7 @@ import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state, query as litQuery } from 'lit/decorators.js';
 import '@components/page-header/page-header';
 import { designTokens } from '../../styles/tokens.css';
+import { srOnly } from '../../styles/sr-only.css';
 import { SearchLocal, SearchLyrics, GetThumbnail, GetThumbnails, GetArtistImageURL, RecordSearchClick } from '@go/explore/Service';
 import { libraryStore } from '../../store/library-store';
 import { exploreCache, ARTIST_IMAGE_CACHE_LIMIT } from '../../store/explore-cache';
@@ -156,6 +157,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
 
     static override styles = [
         designTokens,
+        srOnly,
         exploreLinkStyles,
         css`
             :host {
@@ -1319,6 +1321,9 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
     override render() {
         return html`
             <page-header heading="Explore"></page-header>
+            <div class="sr-only" role="status" aria-live="polite">
+                ${this.liveStatus()}
+            </div>
             ${this.renderSearchInput()}
             ${this.loading
                 ? html`<div class="loading-indicator">Searching\u2026</div>`
@@ -1333,6 +1338,26 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
         `;
     }
 
+    /** "Searching…" and the error block were both silent (a11y.12). */
+    private liveStatus(): string {
+        if (this.error) return this.error;
+
+        if (this.loading) return 'Searching…';
+
+        const results = this.results;
+
+        if (!results) return '';
+
+        const count =
+            (results.artists?.length ?? 0)
+            + (results.releaseGroups?.length ?? 0)
+            + (results.recordings?.length ?? 0);
+
+        return count === 0
+            ? 'No results.'
+            : `${count} result${count === 1 ? '' : 's'}.`;
+    }
+
     private renderSearchInput() {
         const placeholder =
             this.searchMode === 'lyrics'

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

@@ -21,6 +21,7 @@ import { queueStore } from '@store/queue-store';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
 import { FavoritesController } from '@store/controllers/favorites-controller';
@@ -959,6 +960,21 @@ export class GenresView
         );
     };
 
+    /** Shift+F10 / ContextMenu on a focused card. */
+    private openGenreMenuFromKey(
+        e: KeyboardEvent,
+        genre: Genre,
+    ): void {
+        const card = e.currentTarget as HTMLElement | null;
+
+        if (!card) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+        this.contextMenuGenreName = genre.name;
+        this.ctxMenu.openFrom(card);
+    }
+
     private async onContextMenuAction(
         action: string,
     ) {
@@ -1036,7 +1052,7 @@ export class GenresView
                 data-index=${index}
                 tabindex=${this.roving.tabIndexFor(index)}
                 @focus=${() => this.roving.noteFocus(index)}
-                role="button"
+                role="option"
                 aria-label="${genre.name}"
                 aria-selected="${isSelected}"
                 style="
@@ -1055,6 +1071,15 @@ export class GenresView
                         genre,
                     )}
                 @keydown=${(e: KeyboardEvent) => {
+                    if (isContextMenuKey(e)) {
+                        this.openGenreMenuFromKey(
+                            e,
+                            genre,
+                        );
+
+                        return;
+                    }
+
                     if (
                         e.key === 'Enter' ||
                         e.key === ' '
@@ -1109,6 +1134,8 @@ export class GenresView
                     ? html`
                           <div
                               class="context-menu-panel"
+                              role="menu"
+                              aria-label="Genre actions"
                           >
                               <wa-dropdown-item
                                   @click=${() =>
@@ -1295,6 +1322,9 @@ export class GenresView
                 @keydown=${this.roving.handleKeydown}
             >
                 <lit-virtualizer
+                    role="listbox"
+                    aria-label="Genres"
+                    aria-multiselectable="true"
                     .items=${entries}
                     .renderItem=${(entry: GenreEntry) => this.renderGenreCard(entry)}
                     .keyFunction=${(entry: GenreEntry) => entry.genre.name}

frontend/src/components/jobs/job-indicator.ts

@@ -3,6 +3,7 @@ import { customElement, state } from 'lit/decorators.js';
 import '@awesome.me/webawesome/dist/components/icon/icon.js';
 import '@awesome.me/webawesome/dist/components/popup/popup.js';
 import { designTokens } from '../../styles/tokens.css';
+import { srOnly } from '../../styles/sr-only.css';
 import { jobStore } from '@store/job-store';
 import type { Job } from '@store/job-store';
 import { isIndeterminate, progressFraction } from '@store/job-store';
@@ -45,6 +46,7 @@ export class JobIndicator extends LitElement {
 
     static override styles = [
         designTokens,
+        srOnly,
         jobStateStyles,
         css`
             :host {
@@ -337,36 +339,48 @@ export class JobIndicator extends LitElement {
         `;
     }
 
-    private renderTrigger() {
+    /**
+     * What the trigger says. Extracted so the live region can announce
+     * the same sentence — it swung between "Scanning Music", "3
+     * background jobs" and "Finished" in silence (a11y.12).
+     */
+    private triggerLabel(): string {
         const job = this.primaryJob;
         const activeCount = jobStore.activeJobs.length;
+
+        if (activeCount > 1) return `${activeCount} background jobs`;
+
+        if (job && job.state === 'running') return job.title;
+
+        // "Scanning Music" would be a lie for a job that is paused or
+        // queued, so lead with the state instead.
+        if (job) return `${stateLabel(job)} · ${job.title}`;
+
+        return 'Finished';
+    }
+
+    private renderTrigger() {
+        const job = this.primaryJob;
         const hasFailure = jobStore.failedJobs.length > 0;
-
+        const label = this.triggerLabel();
-        let label: string;
-
-        if (activeCount > 1) {
-            label = `${activeCount} background jobs`;
-        } else if (job && job.state === 'running') {
-            label = job.title;
-        } else if (job) {
-            // "Scanning Music" would be a lie for a job that is paused
-            // or queued, so lead with the state instead.
-            label = `${stateLabel(job)} · ${job.title}`;
-        } else {
-            label = 'Finished';
-        }
 
         return html`
             <button
                 class="trigger"
-                aria-haspopup="dialog"
+                aria-haspopup="true"
                 aria-expanded=${this.popoverOpen}
                 title="Background jobs"
                 @click=${this.onTriggerClick}
             >
                 ${this.renderRing(job)}
                 <span class="label">${label}</span>
-                ${hasFailure ? html`<span class="alert-dot"></span>` : nothing}
+                ${hasFailure
+                    ? html`<span
+                          class="alert-dot"
+                          role="img"
+                          aria-label="A background job failed"
+                      ></span>`
+                    : nothing}
             </button>
         `;
     }
@@ -375,7 +389,10 @@ export class JobIndicator extends LitElement {
         const finished = jobStore.finishedJobs;
 
         return html`
-            <div class="panel" role="dialog" aria-label="Background jobs">
+            <!-- Not role="dialog": nothing moves focus into this, traps
+                 Tab or handles Escape, so announcing a dialog that never
+                 receives focus was a promise it does not keep (a11y.17). -->
+            <div class="panel" role="group" aria-label="Background jobs">
                 <div class="panel-header">
                     <span>Background jobs</span>
                     ${finished.length > 0
@@ -415,6 +432,9 @@ export class JobIndicator extends LitElement {
 
     override render() {
         return html`
+            <div class="sr-only" role="status" aria-live="polite">
+                ${this.triggerLabel()}
+            </div>
             <wa-popup
                 placement="bottom-end"
                 distance="8"

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

@@ -11,6 +11,7 @@ import {
 import { PlayerController } from '@store/controllers/player-controller';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { designTokens } from '../../styles/tokens.css';
+import { srOnly } from '../../styles/sr-only.css';
 
 // H-17: at 200 px the artist truncated to "The Orchestra Of" while
 // ~400 px of empty space sat between it and the transport controls.
@@ -74,7 +75,7 @@ export class NowPlaying extends LitElement {
     private lastGeometryKey = '';
     private geometryDirty = true;
 
-    static override styles = [designTokens, exploreLinkStyles, css`
+    static override styles = [designTokens, srOnly, exploreLinkStyles, css`
     :host {
       display: block;
       position: relative;
@@ -287,9 +288,16 @@ export class NowPlaying extends LitElement {
 
     override render() {
         const track = this.player.currentTrack;
+        // Auto-advance changes the track with no announcement of any
+        // kind (a11y.12). The region is in both branches because it has
+        // to already exist when the *first* track arrives.
+        const announcement = track
+            ? `Now playing: ${track.title}${track.artist ? ` by ${track.artist}` : ''}`
+            : '';
 
         if (!track) {
             return html`
+        <div class="sr-only" role="status" aria-live="polite">${announcement}</div>
         <div class="now-playing">
           <div class="cover-art">
             <div class="cover-placeholder"><wa-icon name="music"></wa-icon></div>
@@ -311,6 +319,7 @@ export class NowPlaying extends LitElement {
         const artistScrolling = this.shouldScroll('artist');
 
         return html`
+      <div class="sr-only" role="status" aria-live="polite">${announcement}</div>
       <div class="now-playing">
         <div class="cover-art-wrapper">
           <div

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

@@ -31,8 +31,10 @@ import type { SelectionHost } from '@utils/selection-controller';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import { notificationStore } from '@store/notification-store';
 import { describeError } from '@utils/describe-error';
@@ -342,6 +344,51 @@ export class PlaylistDetails
         );
     }
 
+
+    /** The row holding the roving tab stop. Rows had no keyboard path at
+     *  all before this: not focusable, so Shift+F10 had nowhere to fire
+     *  from and the menu was right-click only (a11y.3). */
+    @state() private focusedIndex = 0;
+
+    private onRowKeydown(e: KeyboardEvent, trackIndex: number): void {
+        const count = this.tracks.length;
+
+        if (count === 0) return;
+
+        const row = e.currentTarget as HTMLElement | null;
+
+        if (isContextMenuKey(e) && row) {
+            e.preventDefault();
+            e.stopPropagation();
+            this.selection.handleContextMenu(String(trackIndex));
+            this.ctxMenu.openFrom(row);
+
+            return;
+        }
+
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            e.stopPropagation();
+            this.handleTrackDblClick(trackIndex);
+
+            return;
+        }
+
+        const next = nextRovingIndex(e.key, this.focusedIndex, count);
+
+        if (next === null) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+        this.focusedIndex = next;
+        void focusRovingRow(
+            this,
+            this.virtualizer,
+            next,
+            (i) => `.track-item[data-index="${i}"]`,
+        );
+    }
+
     private handleTrackDblClick(trackIndex: number) {
         this.selection.clear();
 
@@ -1364,6 +1411,9 @@ export class PlaylistDetails
             </div>
             <lit-virtualizer
                 class="track-scroller"
+                role="listbox"
+                aria-label="Playlist tracks"
+                aria-multiselectable="true"
                 .items=${visibleTracks}
                 .renderItem=${this.renderRow}
                 .keyFunction=${this.rowKey}
@@ -1397,6 +1447,12 @@ export class PlaylistDetails
                     return html`
                         <div
                             class=${classes}
+                            role="option"
+                            aria-selected=${selected}
+                            data-index=${trackIndex}
+                            tabindex=${trackIndex === this.focusedIndex ? 0 : -1}
+                            @keydown=${(e: KeyboardEvent) =>
+                                this.onRowKeydown(e, trackIndex)}
                             draggable=${isPhantom
                                 ? 'false'
                                 : 'true'}
@@ -1526,7 +1582,7 @@ export class PlaylistDetails
                 ${this.ctxMenu.contextMenuOpen
                     ? this.isPhantomSelection()
                         ? html`
-                              <div class="context-menu-panel">
+                              <div class="context-menu-panel" role="menu" aria-label="Track actions">
                                   <wa-dropdown-item
                                       @click=${() =>
                                           this.onContextMenuAction(
@@ -1556,7 +1612,7 @@ export class PlaylistDetails
                               </div>
                           `
                         : html`
-                              <div class="context-menu-panel">
+                              <div class="context-menu-panel" role="menu" aria-label="Track actions">
                                   <wa-dropdown-item
                                       @click=${() =>
                                           this.onContextMenuAction(

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

@@ -25,7 +25,11 @@ import {
     getActiveDragSource,
     getActiveDragPlaylistId,
 } from '@utils/drag-controller';
-import { contextMenuStyles } from '@utils/context-menu-controller.js';
+import {
+    MenuKeyboard,
+    contextMenuStyles,
+    isContextMenuKey,
+} from '@utils/context-menu-controller.js';
 import { describeError } from '@utils/describe-error';
 import { notificationStore } from '@store/notification-store';
 import { confirmAction } from '@components/confirm-dialog/confirm-dialog';
@@ -134,6 +138,13 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
     @query('duplicate-tracks-dialog')
     private duplicateDialog!: DuplicateTracksDialog;
 
+    /** This view renders its own context menu rather than using
+     *  `ContextMenuController`, so it borrows just the keyboard model —
+     *  which is the part that must not exist twice. */
+    private menuKeyboard = new MenuKeyboard(() =>
+        this.closePlaylistContextMenu(),
+    );
+
     private closePlaylistCtxMenuHandler =
         () => this.closePlaylistContextMenu();
 
@@ -1031,6 +1042,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
     private handlePlaylistContextMenu = (
         e: MouseEvent,
         index: number,
+        opener?: HTMLElement,
     ) => {
         e.preventDefault();
         e.stopPropagation();
@@ -1061,13 +1073,39 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                     },
                 };
                 popup.active = true;
+                this.menuKeyboard.open(
+                    popup.querySelector('.context-menu-panel'),
+                    opener,
+                );
             }
         });
     };
 
+    /** Shift+F10 / ContextMenu on a focused playlist header. */
+    private handlePlaylistMenuKey(
+        e: KeyboardEvent,
+        index: number,
+    ): void {
+        const header = e.currentTarget as HTMLElement | null;
+
+        if (!header) return;
+
+        const rect = header.getBoundingClientRect();
+
+        this.handlePlaylistContextMenu(
+            new MouseEvent('contextmenu', {
+                clientX: rect.left + 16,
+                clientY: rect.top + rect.height / 2,
+            }),
+            index,
+            header,
+        );
+    }
+
     private closePlaylistContextMenu() {
         if (!this.playlistContextMenuOpen) return;
 
+        this.menuKeyboard.close();
         this.playlistContextMenuOpen = false;
         this.playlistContextMenuIndex = -1;
 
@@ -1499,6 +1537,8 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
                     ? html`
                           <div
                               class="context-menu-panel"
+                              role="menu"
+                              aria-label="Playlist actions"
                           >
                               ${this.selectedPlaylists.size <= 1
                                   ? html`
@@ -1695,8 +1735,18 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
             >
                 <div
                     class="playlist-header ${this.selectedPlaylists.has(index) ? 'selected' : ''}"
+                    role="button"
+                    tabindex="0"
+                    aria-label=${`Playlist ${entry.summary.Name}`}
                     @click=${(e: MouseEvent) =>
                         this.handlePlaylistHeaderClick(e, index)}
+                    @keydown=${(e: KeyboardEvent) => {
+                        if (isContextMenuKey(e)) {
+                            e.preventDefault();
+                            e.stopPropagation();
+                            this.handlePlaylistMenuKey(e, index);
+                        }
+                    }}
                     @contextmenu=${(e: MouseEvent) =>
                         this.handlePlaylistContextMenu(
                             e,

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

@@ -25,8 +25,10 @@ import type { SelectionHost } from '@utils/selection-controller';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import {
     hasTrackPayload,
@@ -157,6 +159,9 @@ export class QueuePanel
         }
     };
 
+    /** The row holding the roving tab stop. */
+    @state() private focusedIndex = 0;
+
     private panelWidth = DEFAULT_WIDTH;
     private scrollbarDragging = false;
 
@@ -569,6 +574,7 @@ export class QueuePanel
         virtEl.addEventListener('contextmenu', this.onDelegatedContextMenu);
         virtEl.addEventListener('dragstart', this.onDelegatedDragStart);
         virtEl.addEventListener('dragend', this.onTrackDragEnd);
+        virtEl.addEventListener('keydown', this.onDelegatedKeydown);
         this.delegationAttached = true;
     }
 
@@ -651,6 +657,7 @@ export class QueuePanel
             virtEl.removeEventListener('contextmenu', this.onDelegatedContextMenu);
             virtEl.removeEventListener('dragstart', this.onDelegatedDragStart);
             virtEl.removeEventListener('dragend', this.onTrackDragEnd);
+            virtEl.removeEventListener('keydown', this.onDelegatedKeydown);
         }
         this.delegationAttached = false;
     }
@@ -871,6 +878,55 @@ export class QueuePanel
         this.ctxMenu.openAt(e.clientX, e.clientY);
     }
 
+    /**
+     * The queue's rows had no keyboard path at all: not focusable, so
+     * neither Enter nor Shift+F10 had anywhere to fire from, and the
+     * menu — which is the only way to reach most of what a queue row can
+     * do — was right-click only (a11y.3).
+     */
+    private onDelegatedKeydown = (e: KeyboardEvent): void => {
+        const count = this.queue.tracks.length;
+
+        if (count === 0) return;
+
+        const row = (e.target as HTMLElement | null)?.closest<HTMLElement>(
+            '.track-item',
+        );
+
+        if (isContextMenuKey(e) && row) {
+            e.preventDefault();
+            e.stopPropagation();
+            this.selection.handleContextMenu(String(this.focusedIndex));
+            this.ctxMenu.openFrom(row);
+
+            return;
+        }
+
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            e.stopPropagation();
+            this.selection.clear();
+            this.queue.playAtIndex(this.focusedIndex);
+
+            return;
+        }
+
+        const next = nextRovingIndex(e.key, this.focusedIndex, count);
+
+        if (next === null) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+        this.focusedIndex = next;
+        this.selection.handleContextMenu(String(next));
+        void focusRovingRow(
+            this,
+            this.virtualizer,
+            next,
+            (i) => `.track-item[data-index="${i}"]`,
+        );
+    };
+
     private onContextMenuAction(action: string) {
         const indices =
             this.selection.getSelectedIndices();
@@ -1473,6 +1529,10 @@ export class QueuePanel
                 data-testid="queue-row"
                 data-file-path=${track.filePath}
                 draggable="true"
+                role="option"
+                aria-selected=${selected}
+                aria-current=${active ? 'true' : 'false'}
+                tabindex=${index === this.focusedIndex ? 0 : -1}
             >
                 <span class="track-position">
                     ${index + 1}
@@ -1584,6 +1644,9 @@ export class QueuePanel
                         : html`
                               <lit-virtualizer
                                   scroller
+                                  role="listbox"
+                                  aria-label="Queue"
+                                  aria-multiselectable="true"
                                   .items=${tracks}
                                   .renderItem=${this.renderTrackItem}
                                   .keyFunction=${(track: QueueTrack) => track.id}
@@ -1602,7 +1665,7 @@ export class QueuePanel
             >
                 ${this.ctxMenu.contextMenuOpen
                     ? html`
-                          <div class="context-menu-panel">
+                          <div class="context-menu-panel" role="menu" aria-label="Queue track actions">
                               <wa-dropdown-item
                                   @click=${() =>
                                       this.onContextMenuAction(

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

@@ -22,8 +22,10 @@ import type { SelectionHost } from '@utils/selection-controller';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
+import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
 import { FavoritesController } from '@store/controllers/favorites-controller';
 import {
     setDragPayload,
@@ -817,6 +819,51 @@ export class SmartPlaylistDetails
         );
     }
 
+
+    /** The row holding the roving tab stop. Rows had no keyboard path at
+     *  all before this: not focusable, so Shift+F10 had nowhere to fire
+     *  from and the menu was right-click only (a11y.3). */
+    @state() private focusedIndex = 0;
+
+    private onRowKeydown(e: KeyboardEvent, trackIndex: number): void {
+        const count = this.tracks.length;
+
+        if (count === 0) return;
+
+        const row = e.currentTarget as HTMLElement | null;
+
+        if (isContextMenuKey(e) && row) {
+            e.preventDefault();
+            e.stopPropagation();
+            this.selection.handleContextMenu(String(trackIndex));
+            this.ctxMenu.openFrom(row);
+
+            return;
+        }
+
+        if (e.key === 'Enter') {
+            e.preventDefault();
+            e.stopPropagation();
+            this.handleTrackDblClick(trackIndex);
+
+            return;
+        }
+
+        const next = nextRovingIndex(e.key, this.focusedIndex, count);
+
+        if (next === null) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+        this.focusedIndex = next;
+        void focusRovingRow(
+            this,
+            this.virtualizer,
+            next,
+            (i) => `.track-item[data-index="${i}"]`,
+        );
+    }
+
     private handleTrackDblClick(trackIndex: number) {
         this.selection.clear();
 
@@ -1264,6 +1311,9 @@ export class SmartPlaylistDetails
                 <div class="header-cell col-duration">Duration</div>
             </div>
             <lit-virtualizer
+                role="listbox"
+                aria-label="Smart playlist tracks"
+                aria-multiselectable="true"
                 .items=${visibleTracks}
                 .renderItem=${this.renderRow}
                 .keyFunction=${this.rowKey}
@@ -1297,6 +1347,12 @@ export class SmartPlaylistDetails
                     return html`
                         <div
                             class=${classes}
+                            role="option"
+                            aria-selected=${selected}
+                            data-index=${trackIndex}
+                            tabindex=${trackIndex === this.focusedIndex ? 0 : -1}
+                            @keydown=${(e: KeyboardEvent) =>
+                                this.onRowKeydown(e, trackIndex)}
                             draggable=${isPhantom ? 'false' : 'true'}
                             @click=${(e: MouseEvent) =>
                                 this.handleTrackClick(
@@ -1372,7 +1428,7 @@ export class SmartPlaylistDetails
             >
                 ${this.ctxMenu.contextMenuOpen
                     ? html`
-                          <div class="context-menu-panel">
+                          <div class="context-menu-panel" role="menu" aria-label="Track actions">
                               <wa-dropdown-item
                                   @click=${() =>
                                       this.onContextMenuAction(

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

@@ -1,6 +1,7 @@
 import { library } from '@go/models';
 import { LitElement, html, svg, css, nothing } from 'lit';
 import { designTokens } from '../../styles/tokens.css';
+import { srOnly } from '../../styles/sr-only.css';
 import {
     customElement,
     property,
@@ -13,6 +14,7 @@ import { ViewLifecycleMixin } from '@utils/view-lifecycle';
 import {
     ContextMenuController,
     contextMenuStyles,
+    isContextMenuKey,
 } from '@utils/context-menu-controller.js';
 
 import type { ContextMenuHost } from '@utils/context-menu-controller.js';
@@ -231,6 +233,24 @@ export class TrackList
 
         let next = this.focusedIndex;
 
+        // The menu is most of what a row can do, and it was reachable
+        // only by right-click (a11y.3).
+        if (isContextMenuKey(e)) {
+            const track = this.cachedSortedTracks[this.focusedIndex];
+            const row = e.target instanceof HTMLElement
+                ? e.target.closest<HTMLElement>('[role="row"]')
+                : null;
+
+            if (!track || !row) return;
+
+            e.preventDefault();
+            e.stopPropagation();
+            this.selection.handleContextMenu(track.FilePath);
+            this.ctxMenu.openFrom(row);
+
+            return;
+        }
+
         switch (e.key) {
             case 'ArrowDown':
                 next = Math.min(this.focusedIndex + 1, last);
@@ -877,7 +897,7 @@ export class TrackList
         this.requestUpdate();
     };
 
-    static override styles = [designTokens, contextMenuStyles, exploreLinkStyles, css`
+    static override styles = [designTokens, srOnly, contextMenuStyles, exploreLinkStyles, css`
     :host {
       display: flex;
       flex-direction: column;
@@ -1316,6 +1336,28 @@ export class TrackList
         }
     }
 
+    /**
+     * What a screen reader is told about this list, in a sentence.
+     *
+     * Loading, failed, empty and "n results for a search" were all
+     * silent — the list said them in text nobody was watching (a11y.12).
+     */
+    private liveStatus(visible: number): string {
+        if (this.loadError) return this.loadError;
+
+        if (this.loadingTracks) return 'Loading tracks…';
+
+        if (this.tracks.length === 0) return 'No tracks.';
+
+        const term = this.searchCtrl.term.trim();
+
+        if (term === '') return '';
+
+        return visible === 0
+            ? `No tracks match “${term}”.`
+            : `${visible} track${visible === 1 ? '' : 's'} match “${term}”.`;
+    }
+
     /** Loading / failed / genuinely empty, said apart. */
     private renderPlaceholder() {
         if (this.loadError) {
@@ -1858,6 +1900,9 @@ export class TrackList
 
         return html`
       ${this.renderPageHeader()}
+      <div class="sr-only" role="status" aria-live="polite">
+        ${this.liveStatus(visibleTracks.length)}
+      </div>
       ${this.tracks.length === 0
                 ? this.renderPlaceholder()
                 : html`
@@ -1866,19 +1911,31 @@ export class TrackList
               role="grid"
               aria-label="Tracks"
               aria-rowcount=${visibleTracks.length}
+              aria-busy=${this.loadingTracks}
               @keydown=${this.onListKeydown}
             >
             <div class="header-row" role="row">
-              <div role="columnheader"></div>
+              <div role="columnheader" aria-label="Favourite"></div>
               ${cols.map(
                     (col) => html`
                 <div
                   role="columnheader"
+                  tabindex="0"
+                  aria-sort=${this.sortField === col.id
+                          ? (this.sortDirection === 'asc' ? 'ascending' : 'descending')
+                          : 'none'}
                   class="header-cell ${col.align === 'right' ? 'cell-right' : ''}"
                   @click=${() =>
                           this.onHeaderCellClick(
                               col.id,
                           )}
+                  @keydown=${(e: KeyboardEvent) => {
+                          if (e.key !== 'Enter' && e.key !== ' ') return;
+
+                          e.preventDefault();
+                          e.stopPropagation();
+                          this.onHeaderCellClick(col.id);
+                      }}
                 >
                   <span>${col.label}</span>
                   ${this.sortField === col.id
@@ -1930,7 +1987,7 @@ export class TrackList
       >
         ${this.ctxMenu.contextMenuOpen
                 ? html`
-              <div class="context-menu-panel">
+              <div class="context-menu-panel" role="menu" aria-label="Track actions">
                 <wa-dropdown-item
                   @click=${() => this.onContextMenuAction('play')}
                    @mouseenter=${() => this.ctxMenu.closePlaylistSubmenu()}

frontend/src/styles/sr-only.css.ts

@@ -0,0 +1,29 @@
+import { css } from 'lit';
+
+/**
+ * The visually-hidden class, and with it the rule for using one.
+ *
+ * A live region has to be **in the DOM before the text it announces
+ * is**: most screen readers announce a *change* to a region they are
+ * already watching, and ignore a region that appears with its content
+ * already in it. So these regions render unconditionally and empty, and
+ * only their text changes — which is why they are a class rather than a
+ * component that mounts on demand.
+ *
+ * `clip-path` rather than `display: none` or `visibility: hidden`, both
+ * of which take the element out of the accessibility tree along with the
+ * layout, which would defeat the point.
+ */
+export const srOnly = css`
+    .sr-only {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        margin: -1px;
+        padding: 0;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+        border: 0;
+    }
+`;

frontend/src/utils/context-menu-controller.ts

@@ -33,6 +33,195 @@ export interface ContextMenuHost
 /** Submenu close delay in milliseconds. */
 const SUBMENU_CLOSE_DELAY = 150;
 
+/** A menu item, focusable and clickable. Web Awesome sets `role` itself. */
+type MenuItem = HTMLElement & { active?: boolean; disabled?: boolean };
+
+/**
+ * Whether a keypress is the conventional "open the context menu" one.
+ * Shift+F10 is the long-standing binding; `ContextMenu` is the dedicated
+ * key on keyboards that have one.
+ */
+export function isContextMenuKey(e: KeyboardEvent): boolean {
+    return e.key === 'ContextMenu' || (e.shiftKey && e.key === 'F10');
+}
+
+/**
+ * The keyboard model for an open menu panel: focus the first item,
+ * Arrow/Home/End to move, Enter/Space to activate, Escape/Tab to close,
+ * and focus back where it came from.
+ *
+ * It is a standalone class rather than part of `ContextMenuController`
+ * because `playlist-view` renders a menu without using that controller,
+ * and the one thing worse than a menu with no keyboard model is two
+ * menus with two different ones.
+ */
+export class MenuKeyboard {
+    private panel: HTMLElement | null = null;
+
+    private restoreFocusTo: HTMLElement | null = null;
+
+    constructor(private readonly onClose: () => void) {}
+
+    /** Bind to a freshly-opened panel and focus its first item. */
+    open(panel: HTMLElement | null, opener?: HTMLElement | null): void {
+        if (!panel || this.panel === panel) return;
+
+        this.detach();
+        this.panel = panel;
+        this.restoreFocusTo = opener ?? deepActiveElement();
+        panel.addEventListener('keydown', this.onKeydown);
+        void this.focusFirstItem(panel);
+    }
+
+    /**
+     * Focus the first item, once the items are items.
+     *
+     * The host's `updateComplete` resolves before the `wa-dropdown-item`s
+     * inside the panel have run their own first update — and `role` is
+     * one of the things they set there. Querying by role at that moment
+     * finds nothing, which reads exactly like a menu that opened and
+     * refused to take focus.
+     */
+    private async focusFirstItem(panel: HTMLElement): Promise<void> {
+        const candidates = [
+            ...panel.querySelectorAll<MenuItem & { updateComplete?: Promise<boolean> }>(
+                'wa-dropdown-item, [role^="menuitem"]',
+            ),
+        ];
+
+        await Promise.all(candidates.map((el) => el.updateComplete ?? null));
+
+        // …and once the popup has positioned itself. `wa-popup` places the
+        // panel on an animation frame, and `focus()` on a not-yet-shown
+        // element is a silent no-op — which looks identical to a menu
+        // that opened and refused to take focus.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            // Bail if the menu closed while we waited.
+            if (this.panel !== panel) return;
+
+            const first = this.items()[0];
+
+            this.focusItem(first);
+
+            if (first && panel.contains(deepActiveElement())) return;
+
+            await new Promise((resolve) => requestAnimationFrame(resolve));
+        }
+    }
+
+    /**
+     * Unbind, and give focus back if the menu had it. A click elsewhere
+     * closes the menu too, and yanking focus back to the row the user
+     * right-clicked a moment ago is worse than leaving it alone.
+     */
+    close(): void {
+        const restoreTo = this.restoreFocusTo;
+        const hadFocus = this.panel?.contains(deepActiveElement()) ?? false;
+
+        this.detach();
+
+        if (hadFocus && restoreTo?.isConnected) restoreTo.focus();
+    }
+
+    private detach(): void {
+        this.panel?.removeEventListener('keydown', this.onKeydown);
+        this.panel = null;
+        this.restoreFocusTo = null;
+    }
+
+    /** The enabled items, in DOM order. */
+    private items(): MenuItem[] {
+        if (!this.panel) return [];
+
+        return [
+            ...this.panel.querySelectorAll<MenuItem>(
+                'wa-dropdown-item, [role^="menuitem"]',
+            ),
+        ].filter(
+            (item) =>
+                !item.disabled && item.getAttribute('aria-disabled') !== 'true',
+        );
+    }
+
+    private focusItem(item: MenuItem | undefined): void {
+        if (!item) return;
+
+        // `active` is what Web Awesome keys an item's tabindex and its
+        // highlight off, so moving focus without it leaves the highlight
+        // on whichever item the mouse last touched.
+        for (const other of this.items()) other.active = other === item;
+
+        item.tabIndex = 0;
+        item.focus();
+    }
+
+    private onKeydown = (e: KeyboardEvent): void => {
+        const items = this.items();
+
+        if (items.length === 0) return;
+
+        const current = items.findIndex(
+            (item) => item === e.target || item.contains(e.target as Node),
+        );
+        const move = (next: number): void => {
+            e.preventDefault();
+            e.stopPropagation();
+            this.focusItem(items[(next + items.length) % items.length]);
+        };
+
+        switch (e.key) {
+        case 'ArrowDown':
+            move(current + 1);
+
+            break;
+        case 'ArrowUp':
+            move(current - 1);
+
+            break;
+        case 'Home':
+            move(0);
+
+            break;
+        case 'End':
+            move(items.length - 1);
+
+            break;
+        case 'Escape':
+        case 'Tab':
+            // Tab closes rather than moving through the menu: the panel
+            // is a bare popup in the host's shadow root, so tabbing out
+            // of it lands in the page behind with the menu still open.
+            e.preventDefault();
+            e.stopPropagation();
+            this.onClose();
+
+            break;
+        case 'Enter':
+        case ' ':
+            // These items are in a `wa-popup`, not a `wa-dropdown`, so
+            // nothing upstream turns a keypress into an activation.
+            e.preventDefault();
+            e.stopPropagation();
+            items[current]?.click();
+
+            break;
+        default:
+            break;
+        }
+    };
+}
+
+/** The focused element, resolved through shadow roots. */
+function deepActiveElement(): HTMLElement | null {
+    let el = document.activeElement as HTMLElement | null;
+
+    while (el?.shadowRoot?.activeElement) {
+        el = el.shadowRoot.activeElement as HTMLElement;
+    }
+
+    return el;
+}
+
 /**
  * Reusable context menu controller that manages the open/close
  * state of a wa-popup context menu with an optional playlist
@@ -116,6 +305,7 @@ export class ContextMenuController
 
     hostDisconnected(): void {
         this.detach();
+        this.keyboard.close();
         this.clearSubmenuCloseTimer();
     }
 
@@ -162,8 +352,13 @@ export class ContextMenuController
     /**
      * Open the context menu at the given screen
      * coordinates using a virtual anchor.
+     *
+     * `opener` is where focus goes back to on close. It defaults to
+     * whatever was focused when the menu opened, which is right for a
+     * right-click (usually nothing) and for a keyboard open (the row).
      */
-    openAt(clientX: number, clientY: number): void {
+    openAt(clientX: number, clientY: number, opener?: HTMLElement | null): void {
+        this.pendingOpener = opener ?? deepActiveElement();
         this.contextMenuOpen = true;
         this.host.requestUpdate();
 
@@ -184,9 +379,27 @@ export class ContextMenuController
                 },
             };
             popup.active = true;
+
+            this.bindKeyboard();
         });
     }
 
+    /**
+     * Open the menu from an element rather than from a pointer — the
+     * Shift+F10 / ContextMenu-key path. Anchors to the element's own box
+     * so the menu appears where the thing it acts on is, and restores
+     * focus there on close.
+     */
+    openFrom(el: HTMLElement): void {
+        const rect = el.getBoundingClientRect();
+
+        this.openAt(rect.left + 16, rect.top + rect.height / 2, el);
+    }
+
+    // =================================================================
+    // KEYBOARD
+    // =================================================================
+
     /**
      * Close the context menu and playlist submenu.
      * Notifies the host via `onContextMenuClose()` so
@@ -195,12 +408,12 @@ export class ContextMenuController
     close(): void {
         if (!this.contextMenuOpen) return;
 
+        this.keyboard.close();
         this.closePlaylistSubmenu();
         this.contextMenuOpen = false;
         this.playlistFilePaths = [];
 
-        const popup =
+        const popup = this.host.getContextMenuPopup();
-            this.host.getContextMenuPopup();
 
         if (popup) {
             popup.active = false;
@@ -210,6 +423,25 @@ export class ContextMenuController
         this.host.requestUpdate();
     }
 
+    /** The menu's keyboard model, shared with the one host that renders
+     *  a context menu without this controller. */
+    private keyboard = new MenuKeyboard(() => this.close());
+
+    /** The element focus returns to, captured at open and handed to the
+     *  keyboard model once the panel exists. */
+    private pendingOpener: HTMLElement | null = null;
+
+    private get panel(): HTMLElement | null {
+        const popup = this.host.getContextMenuPopup();
+
+        return popup?.querySelector('.context-menu-panel') ?? null;
+    }
+
+    private bindKeyboard(): void {
+        this.keyboard.open(this.panel, this.pendingOpener);
+        this.pendingOpener = null;
+    }
+
     // =================================================================
     // PLAYLIST SUBMENU
     // =================================================================

frontend/src/utils/roving-rows.ts

@@ -0,0 +1,70 @@
+/**
+ * A roving tab stop over a virtualized list of rows.
+ *
+ * Three lists needed the same thing at once — the queue panel and both
+ * playlist detail views — because a context menu opened with Shift+F10
+ * needs a focused row to open *from*, and none of the three had one:
+ * their rows were plain `<div>`s with no `tabindex` and no `role`.
+ *
+ * `track-list` deliberately does not use this. Its equivalent predates
+ * it, carries selection semantics (shift-extend, ctrl-toggle) that the
+ * other three do not have, and is pinned by its own tests; converting it
+ * would be a rewrite of the one list that already worked.
+ *
+ * Two things here are not optional:
+ *
+ * - **The virtualizer is told the index changed.** Rows come from the
+ *   `virtualize` directive, which re-renders on the virtualizer's *own*
+ *   properties — a host re-render does not move a `tabindex`.
+ * - **Focus is taken after the update.** The row for an index that was
+ *   off-screen does not exist until the virtualizer has scrolled to it.
+ */
+import type { LitVirtualizer } from '@lit-labs/virtualizer';
+
+export interface RovingRowsHost {
+    requestUpdate(): void;
+    updateComplete: Promise<boolean>;
+}
+
+/** The keys this handles, and what they mean given a row count. */
+export function nextRovingIndex(
+    key: string,
+    current: number,
+    count: number,
+): number | null {
+    switch (key) {
+    case 'ArrowDown':
+        return Math.min(current + 1, count - 1);
+    case 'ArrowUp':
+        return Math.max(current - 1, 0);
+    case 'Home':
+        return 0;
+    case 'End':
+        return count - 1;
+    default:
+        return null;
+    }
+}
+
+/**
+ * Move the tab stop to `index` and put focus on it.
+ *
+ * `rowSelector` receives the index and must return a selector matching
+ * that row inside the virtualizer's light DOM.
+ */
+export async function focusRovingRow(
+    host: RovingRowsHost,
+    virtualizer: LitVirtualizer | undefined,
+    index: number,
+    rowSelector: (index: number) => string,
+): Promise<void> {
+    host.requestUpdate();
+    virtualizer?.requestUpdate();
+    virtualizer?.scrollToIndex(index, 'nearest');
+
+    await host.updateComplete;
+
+    virtualizer
+        ?.querySelector<HTMLElement>(rowSelector(index))
+        ?.focus();
+}

frontend/test/components/aria-tail.test.ts

@@ -0,0 +1,193 @@
+/**
+ * The ARIA tail of `a11y.md`, pinned.
+ *
+ * Every assertion here is a finding that was reproduced in the running
+ * app first. Three of them are the kind that no other tier can see: a
+ * grid that sorts and never says so, a list whose loading/empty/failed
+ * states are text nobody is watching, and `aria-selected` on
+ * `role="button"`, which is not merely useless but *invalid* — the
+ * attribute is dropped, so the state the whole ctrl/shift interaction
+ * exists to produce was invisible.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/track-list/track-list';
+import '@components/artists-view/artists-view';
+import '@components/genres-view/genres-view';
+import { emit, stub, flush, resetHarness } from '@test/support/harness';
+import { Events } from '../../src/events';
+import { fixture, shadow, shadowAll } from '@test/support/render';
+import { searchStore } from '@store/search-store';
+
+/**
+ * The searchable columns' accessors read these fields and call
+ * `.toLowerCase()` on the result, so a sparse fixture throws inside the
+ * ranker rather than failing an assertion. Real tracks always carry
+ * them; a fixture has to as well.
+ */
+const TRACKS = [
+  {
+    FilePath: '/m/a.mp3',
+    TrackName: 'Departure',
+    ArtistName: 'Aurora Fields',
+    Album: 'Glass Harbour',
+    AlbumArtist: 'Aurora Fields',
+    Composer: '',
+    Genre: ['Ambient'],
+    TrackLength: 4000,
+  },
+  {
+    FilePath: '/m/b.mp3',
+    TrackName: 'Tideline',
+    ArtistName: 'Aurora Fields',
+    Album: 'Glass Harbour',
+    AlbumArtist: 'Aurora Fields',
+    Composer: '',
+    Genre: ['Ambient'],
+    TrackLength: 6000,
+  },
+];
+
+const ARTISTS = [
+  { ID: 1, Name: 'Alpha', AlbumCount: 2, TrackCount: 9 },
+  { ID: 2, Name: 'Beta', AlbumCount: 1, TrackCount: 4 },
+];
+
+const GENRES = [
+  { name: 'Ambient', count: 12 },
+  { name: 'Doom', count: 3 },
+];
+
+function sized(el: HTMLElement): void {
+  el.style.display = 'block';
+  el.style.height = '600px';
+  el.style.width = '900px';
+}
+
+async function settle(el: LitElement): Promise<void> {
+  await flush();
+  await el.updateComplete;
+  await new Promise((r) => setTimeout(r, 80));
+}
+
+describe('the track list says how it is sorted', () => {
+  beforeEach(async () => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllTracks', TRACKS);
+    stub('library.Library.GetAllAlbums', []);
+    emit(Events.LibraryScanComplete);
+  });
+
+  it('gives every column an aria-sort, defaulting to none', async () => {
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const sorts = shadowAll(el, '.header-cell[role="columnheader"]').map((h) =>
+      h.getAttribute('aria-sort'),
+    );
+
+    expect(sorts.length, 'no sortable column headers').toBeGreaterThan(0);
+    // The list opens in file order — `sortField` is null — so no column
+    // claims to be the sort until one is chosen.
+    expect(sorts.every((s) => s === 'none')).toBe(true);
+  });
+
+  it('changes aria-sort when a column is activated from the keyboard', async () => {
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const title = shadowAll(el, '.header-cell[role="columnheader"]').find((h) =>
+      /track name/i.test(h.textContent ?? ''),
+    );
+
+    expect(title, 'no Track Name column header').toBeTruthy();
+
+    // Reading the DOM synchronously after this would report the state
+    // *before* Lit rendered, which is how a fix for nothing gets shipped.
+    title!.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, composed: true }),
+    );
+    await settle(el);
+
+    const after = shadowAll(el, '.header-cell[role="columnheader"]').find((h) =>
+      /track name/i.test(h.textContent ?? ''),
+    );
+
+    expect(after?.getAttribute('aria-sort')).toBe('ascending');
+  });
+});
+
+describe('the track list has a voice for its own state', () => {
+  beforeEach(() => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllAlbums', []);
+  });
+
+  it('announces the result of a search that matches nothing', async () => {
+    stub('library.Library.GetAllTracks', TRACKS);
+    emit(Events.LibraryScanComplete);
+
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const live = shadow(el, '[role="status"][aria-live="polite"]');
+
+    // The region exists *before* it has anything to say — a region that
+    // appears with its text already in it is not announced by most
+    // screen readers.
+    expect(live, 'no live region on the track list').toBeTruthy();
+
+    searchStore.setCurrentView('tracks');
+    searchStore.setTerm('nothing matches this');
+    await settle(el);
+
+    expect(shadow(el, '[role="status"]')?.textContent?.trim()).toMatch(
+      /No tracks match/i,
+    );
+  });
+});
+
+describe('a selectable grid is a listbox, not a row of buttons', () => {
+  beforeEach(() => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllArtists', ARTISTS);
+    stub('library.Library.GetAllGenresWithCounts', GENRES);
+    stub('library.Library.GetAllTracks', []);
+    stub('library.Library.GetAllAlbums', []);
+    emit(Events.LibraryScanComplete);
+  });
+
+  it.each([
+    ['artists-view', '.artist-card'],
+    ['genres-view', '.genre-card'],
+  ])('%s cards are options carrying aria-selected', async (tag, cardSelector) => {
+    const el = await fixture<LitElement>(tag);
+
+    sized(el);
+    await settle(el);
+
+    const card = shadowAll(el, cardSelector)[0];
+
+    expect(card, `no cards rendered in ${tag}`).toBeTruthy();
+
+    // role=button + aria-selected is invalid: the attribute is dropped,
+    // and the selection is invisible to anything but a sighted user.
+    expect(card!.getAttribute('role')).toBe('option');
+    expect(card!.hasAttribute('aria-selected')).toBe(true);
+
+    const list = shadow(el, '[role="listbox"]');
+
+    expect(list, `${tag} has options with no listbox`).toBeTruthy();
+    expect(list!.getAttribute('aria-multiselectable')).toBe('true');
+  });
+});

frontend/test/components/menu-keyboard.test.ts

@@ -0,0 +1,176 @@
+/**
+ * The context menu has a keyboard model, and it is one model.
+ *
+ * `a11y.3`: the panel is a bare `wa-popup` holding `wa-dropdown-item`s.
+ * Web Awesome gives each item `role="menuitem"`, but nothing gave the
+ * container `role="menu"`, nothing moved focus into it, nothing handled
+ * Arrow/Escape, and nothing restored focus. Play, Add to Queue, Play
+ * Next, Add to Playlist, Favourite and Track Details — most of which
+ * have no other route — were mouse-only.
+ *
+ * `MenuKeyboard` is that model, standalone rather than part of
+ * `ContextMenuController`, because `playlist-view` renders a menu
+ * without the controller and two menus with two keyboard models is the
+ * thing this is meant to prevent.
+ *
+ * The two non-obvious parts are pinned below, both of which cost a cycle
+ * when they were wrong:
+ *
+ * - The items are not items yet when the host's `updateComplete`
+ *   resolves. `wa-dropdown-item` sets its `role` in its *own* first
+ *   update, so a `[role^="menuitem"]` query at that moment finds
+ *   nothing and the menu opens without taking focus.
+ * - Focus is only taken back on close if the menu had it. A click
+ *   elsewhere closes the menu too, and pulling focus to the row the
+ *   user right-clicked a moment ago would be worse than leaving it.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+
+import { MenuKeyboard, isContextMenuKey } from '@utils/context-menu-controller';
+
+/** A panel of plain elements carrying the roles Web Awesome would set. */
+function panelWith(labels: string[]): HTMLElement {
+  const panel = document.createElement('div');
+
+  panel.className = 'context-menu-panel';
+  panel.setAttribute('role', 'menu');
+
+  for (const label of labels) {
+    const item = document.createElement('div');
+
+    item.setAttribute('role', 'menuitem');
+    item.textContent = label;
+    panel.append(item);
+  }
+
+  document.body.append(panel);
+
+  return panel;
+}
+
+function press(target: EventTarget, key: string): void {
+  target.dispatchEvent(
+    new KeyboardEvent('keydown', { key, bubbles: true, composed: true }),
+  );
+}
+
+/** The focused element, resolved the way the app resolves it. */
+function active(): Element | null {
+  let el = document.activeElement;
+
+  while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
+
+  return el;
+}
+
+describe('the context menu key', () => {
+  it('is Shift+F10 and the ContextMenu key, and nothing else', () => {
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'ContextMenu' }))).toBe(
+      true,
+    );
+    expect(
+      isContextMenuKey(new KeyboardEvent('keydown', { key: 'F10', shiftKey: true })),
+    ).toBe(true);
+    // F10 alone is a menu-bar convention we do not own.
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'F10' }))).toBe(false);
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'Enter' }))).toBe(false);
+  });
+});
+
+describe('MenuKeyboard', () => {
+  let panel: HTMLElement;
+  let opener: HTMLButtonElement;
+  let closed: number;
+  let keyboard: MenuKeyboard;
+
+  beforeEach(async () => {
+    closed = 0;
+    opener = document.createElement('button');
+    opener.textContent = 'The row';
+    document.body.append(opener);
+    opener.focus();
+
+    panel = panelWith(['Play', 'Add to Queue', 'Track Details']);
+    keyboard = new MenuKeyboard(() => {
+      closed++;
+      keyboard.close();
+    });
+    keyboard.open(panel, opener);
+
+    // Focus is taken across at least one frame, because a popup that has
+    // not positioned itself yet cannot be focused.
+    await new Promise((r) => requestAnimationFrame(r));
+  });
+
+  afterEach(() => {
+    keyboard.close();
+    panel.remove();
+    opener.remove();
+  });
+
+  it('focuses the first item on open', () => {
+    expect(active()?.textContent).toBe('Play');
+  });
+
+  it('moves with the arrows and wraps', () => {
+    press(active()!, 'ArrowDown');
+    expect(active()?.textContent).toBe('Add to Queue');
+
+    press(active()!, 'ArrowUp');
+    expect(active()?.textContent).toBe('Play');
+
+    // Up from the first item wraps to the last, which is what a menu
+    // does and what a listbox does not.
+    press(active()!, 'ArrowUp');
+    expect(active()?.textContent).toBe('Track Details');
+  });
+
+  it('goes to the ends with Home and End', () => {
+    press(active()!, 'End');
+    expect(active()?.textContent).toBe('Track Details');
+
+    press(active()!, 'Home');
+    expect(active()?.textContent).toBe('Play');
+  });
+
+  it('activates the focused item with Enter', () => {
+    let clicked = '';
+
+    for (const item of panel.querySelectorAll('[role="menuitem"]')) {
+      item.addEventListener('click', () => {
+        clicked = item.textContent ?? '';
+      });
+    }
+
+    press(active()!, 'ArrowDown');
+    press(active()!, 'Enter');
+
+    expect(clicked).toBe('Add to Queue');
+  });
+
+  it('closes on Escape and gives focus back to the opener', () => {
+    press(active()!, 'Escape');
+
+    expect(closed).toBe(1);
+    expect(active()).toBe(opener);
+  });
+
+  it('closes on Tab rather than letting focus escape the panel', () => {
+    press(active()!, 'Tab');
+
+    expect(closed).toBe(1);
+    expect(active()).toBe(opener);
+  });
+
+  it('leaves focus alone when the menu did not have it', () => {
+    const elsewhere = document.createElement('button');
+
+    document.body.append(elsewhere);
+    elsewhere.focus();
+
+    keyboard.close();
+
+    expect(active()).toBe(elsewhere);
+    elsewhere.remove();
+  });
+});