feat: add playback keyboard shortcuts (#474)

- Space: play/pause
- Left/Right arrows: seek ±10 seconds
- J/L: previous/next track
- M: mute/unmute

All shortcuts respect input focus and are disabled when search modal is open.

Also fixes AGENTS.md to reflect that STATUS.md is now tracked.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[e-mail]>

AGENTS.md

···
 - check the justfiles. there's a root one, one for the backend, one for the frontend, and one for the transcoder etc
 
 ## 🚨 Critical Rules & Workflows
-*   **Read `STATUS.md` First:** Always check for active tasks and known issues. This file is NEVER tracked in git.
+*   **Read `STATUS.md` First:** Always check for active tasks and known issues.
 *   **Workflow:**
     *   Use **GitHub Issues** (not Linear).
     *   **PRs:** Always create for review; never push to main directly.
···
 │   └── src/lib/      # Components & State (.svelte.ts)
 ├── scripts/          # Admin scripts (uv run scripts/...)
 ├── docs/             # Architecture & Guides
-└── STATUS.md         # Living status document (Untracked)
+└── STATUS.md         # Living status document
 ```
 
 this file ("AGENTS.md") is symlinked to `CLAUDE.md` and `GEMINI.md` for maximal compatibility.

docs/frontend/keyboard-shortcuts.md

···
 - `aria-label="toggle queue (Q)"` for screen readers
 - tooltip shows keyboard hint
 
+---
+
+## playback shortcuts
+
+all playback shortcuts require a track to be loaded and are disabled when the search modal is open.
+
+### Space - play/pause
+
+toggles playback of the current track.
+
+### Left Arrow - seek backward
+
+seeks backward 10 seconds in the current track.
+
+### Right Arrow - seek forward
+
+seeks forward 10 seconds in the current track.
+
+### J - previous track
+
+goes to the previous track in the queue. if more than 3 seconds into the current track, restarts it instead.
+
+### L - next track
+
+advances to the next track in the queue (if available).
+
+### M - mute/unmute
+
+toggles mute. restores previous volume level when unmuting.
+
+---
+
 ## adding new shortcuts
 
 when adding keyboard shortcuts:
···
 ## future candidates
 
 potential shortcuts to consider:
-- **space** - play/pause (when not focused on button)
-- **arrow keys** - skip forward/back (context-aware)
-- **shift + arrow** - navigate queue
 - **/** - focus search (alternative to Cmd/Ctrl+K)
 - **T** - cycle theme (dark/light/system)
+- **S** - shuffle queue
 
 ## design principles
 

frontend/src/routes/+layout.svelte

···
 	import { auth } from '$lib/auth.svelte';
 	import { preferences } from '$lib/preferences.svelte';
 	import { player } from '$lib/player.svelte';
+	import { queue } from '$lib/queue.svelte';
 	import { search } from '$lib/search.svelte';
 	import { browser } from '$app/environment';
 	import type { LayoutData } from './$types';
···
 		document.documentElement.style.setProperty('--queue-width', queueWidth);
 	});
 
+	const SEEK_AMOUNT = 10; // seconds
+	let previousVolume = 0.7; // for mute toggle
+
 	function handleKeyboardShortcuts(event: KeyboardEvent) {
 		// Cmd/Ctrl+K: toggle search
 		if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
···
 			return;
 		}
 
+		// ignore playback shortcuts when search modal is open
+		if (search.isOpen) {
+			return;
+		}
+
+		const key = event.key.toLowerCase();
+
 		// toggle queue on 'q' key
-		if (event.key.toLowerCase() === 'q') {
+		if (key === 'q') {
 			event.preventDefault();
 			toggleQueue();
+			return;
+		}
+
+		// playback shortcuts - only when a track is loaded
+		if (!player.currentTrack) {
+			return;
+		}
+
+		switch (event.key) {
+			case ' ': // space - play/pause
+				event.preventDefault();
+				player.togglePlayPause();
+				break;
+
+			case 'ArrowLeft': // seek backward
+				event.preventDefault();
+				seekBy(-SEEK_AMOUNT);
+				break;
+
+			case 'ArrowRight': // seek forward
+				event.preventDefault();
+				seekBy(SEEK_AMOUNT);
+				break;
+
+			case 'j': // previous track (youtube-style)
+			case 'J':
+				event.preventDefault();
+				handlePreviousTrack();
+				break;
+
+			case 'l': // next track (youtube-style)
+			case 'L':
+				event.preventDefault();
+				if (queue.hasNext) {
+					queue.next();
+				}
+				break;
+
+			case 'm': // mute/unmute
+			case 'M':
+				event.preventDefault();
+				toggleMute();
+				break;
+		}
+	}
+
+	function seekBy(seconds: number) {
+		if (!player.audioElement || !player.duration) return;
+
+		const newTime = Math.max(0, Math.min(player.duration, player.currentTime + seconds));
+		player.currentTime = newTime;
+		player.audioElement.currentTime = newTime;
+	}
+
+	function handlePreviousTrack() {
+		const RESTART_THRESHOLD = 3; // restart if more than 3 seconds in
+
+		if (player.currentTime > RESTART_THRESHOLD) {
+			// restart current track
+			player.currentTime = 0;
+			if (player.audioElement) {
+				player.audioElement.currentTime = 0;
+			}
+		} else if (queue.hasPrevious) {
+			// go to previous track
+			queue.previous();
+		} else {
+			// restart from beginning
+			player.currentTime = 0;
+			if (player.audioElement) {
+				player.audioElement.currentTime = 0;
+			}
+		}
+	}
+
+	function toggleMute() {
+		if (player.volume > 0) {
+			previousVolume = player.volume;
+			player.volume = 0;
+		} else {
+			player.volume = previousVolume || 0.7;
 		}
 	}