feat: init

.envrc

···
+use nix

.gitignore

···
+.direnv
+.DS_Store
+node_modules

.tangled/workflows/wisp-deploy.yml

···
+when:
+  - event: ["push"]
+    branch: ["main"]
+
+engine: "nixery"
+dependencies:
+  nixpkgs:
+    - nodejs
+    - coreutils
+    - curl
+    - glibc
+    - pnpm
+
+environment:
+  SITE_PATH: "src"
+  SITE_NAME: "tinysub"
+  WISP_HANDLE: "devins.page"
+
+steps:
+  - name: deploy
+    command: |
+      pnpm wispctl deploy "$WISP_HANDLE" \
+        --path "$SITE_PATH" \
+        --site "$SITE_NAME" \
+        --password "$WISP_APP_PASSWORD"

package.json

···
+{
+	"name": "tinysub",
+	"version": "1.0.0",
+	"dependencies": {
+		"prettier": "^3.8.1",
+		"wispctl": "^1.0.10"
+	},
+	"prettier": {
+		"useTabs": true
+	}
+}

pnpm-lock.yaml

···
+lockfileVersion: "9.0"
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+  .:
+    dependencies:
+      prettier:
+        specifier: ^3.8.1
+        version: 3.8.1
+      wispctl:
+        specifier: ^1.0.10
+        version: 1.0.10
+
+packages:
+  prettier@3.8.1:
+    resolution:
+      {
+        integrity: sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==,
+      }
+    engines: { node: ">=14" }
+    hasBin: true
+
+  wispctl@1.0.10:
+    resolution:
+      {
+        integrity: sha512-yn8yBU/9qMU252Vf8n97a26k0BPsMDqoTrUm4hOLHD8QJ6z9HheuZJtlqeNuMbY9L8NBCZw7vf4xRGjt0xDt4w==,
+      }
+    hasBin: true
+
+snapshots:
+  prettier@3.8.1: {}
+
+  wispctl@1.0.10: {}

shell.nix

···
+{pkgs ? import <nixpkgs> {}}:
+pkgs.mkShell {
+  buildInputs = with pkgs; [
+    nodejs
+    pnpm
+  ];
+}

src/css/base.css

···
+/* var */
+:root {
+	color-scheme: light dark;
+
+	/* borders */
+	--border: light-dark(hsl(0 0% 0% / 0.25), hsl(0 0% 100% / 0.25));
+	--border-subtle: light-dark(hsl(0 0% 0% / 0.1), hsl(0 0% 100% / 0.1));
+
+	/* backgrounds */
+	--bg-secondary: light-dark(hsl(0 0% 0% / 0.05), hsl(0 0% 100% / 0.05));
+	--bg-tertiary: light-dark(hsl(0 0% 0% / 0.1), hsl(0 0% 100% / 0.1));
+	--bg-context-menu: light-dark(hsl(0 0% 100% / 0.75), hsl(0 0% 10% / 0.75));
+
+	/* state colors */
+	--playing: hsl(200 90% 50% / 0.25);
+	--playing-pulse: hsl(200 90% 50% / 0.5);
+	--selection-color: hsl(220 80% 45%);
+	--error-color: hsl(0 80% 50%);
+
+	/* cover art sizing (customize via settings) */
+	--icon: 16px;
+	--art-album: 32px;
+	--art-artist: 16px;
+	--art-song: 16px;
+}
+
+/* resets */
+* {
+	margin: 0;
+	padding: 0;
+}
+
+/* document stuff */
+html {
+	font-size: 0.8125rem;
+}
+
+body {
+	font-family: system-ui, sans-serif;
+	overflow: hidden;
+	user-select: none;
+	-webkit-user-select: none;
+}
+
+/* interactive elements */
+a,
+button,
+[role="button"] {
+	cursor: default;
+}
+
+/* responsive sizing for mobile */
+@media (max-width: 768px) {
+	html {
+		font-size: 1rem;
+	}
+}

src/css/components.css

···
+/* button base styling (all buttons use flex for icon + text alignment) */
+button {
+	background: none;
+	border: none;
+	padding: 0;
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	color: inherit;
+	font: inherit;
+}
+
+/* pulsing animation for currently playing track */
+@keyframes pulse {
+	0%,
+	100% {
+		background-color: var(--playing);
+	}
+	50% {
+		background-color: var(--playing-pulse);
+	}
+}
+
+/* sidebar library section headings */
+#sidebar h2 {
+	font-size: 1rem;
+	margin-top: 0.5rem;
+}
+
+#sidebar h2 a {
+	color: inherit;
+	text-decoration: none;
+}
+
+#sidebar ul {
+	list-style: none;
+}
+
+#sidebar li {
+	margin-top: 0.5rem;
+}
+
+/* tree item container (expand button + name + actions) */
+.tree-item {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+/* toggle button and item name (with art and text) */
+.tree-toggle,
+.tree-name {
+	color: inherit;
+	text-decoration: none;
+	flex: 1;
+	display: flex;
+	gap: 0.5rem;
+	align-items: center;
+	min-width: 0;
+}
+
+/* ellipsis text overflow for item names */
+.tree-toggle span,
+.tree-name span {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+/* disabled state for action buttons */
+.tree-action.disabled {
+	opacity: 0.5;
+}
+
+/* artist-level art icons */
+.tree-toggle img,
+.tree-name img {
+	width: var(--art-artist);
+	height: var(--art-artist);
+	aspect-ratio: 1 / 1;
+	object-fit: cover;
+}
+
+/* album-level art icons (nested under artists) */
+ul.nested > li .tree-toggle img,
+ul.nested > li .tree-name img {
+	width: var(--art-album);
+	height: var(--art-album);
+}
+
+/* song art in queue table */
+.queue-cover {
+	width: var(--art-song);
+	height: var(--art-song);
+	aspect-ratio: 1 / 1;
+	object-fit: cover;
+	flex-shrink: 0;
+}
+
+/* favorite button toggle states */
+.queue-favorite {
+	opacity: 0.25;
+}
+
+.queue-favorite:hover {
+	opacity: 0.7;
+}
+
+.queue-favorite.favorited {
+	opacity: 1;
+}
+
+/* nested tree lists */
+.nested {
+	list-style: none;
+	margin-left: 1rem;
+}
+
+.nested li {
+	margin-top: 0.25rem;
+}
+
+/* currently playing track info panel */
+#now-playing {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 0.75rem;
+	padding: 1rem 0;
+	border-top: 1px solid var(--border-subtle);
+	flex-shrink: 0;
+}
+
+#cover-art {
+	width: 128px;
+	height: 128px;
+	object-fit: cover;
+}
+
+#track-info {
+	text-align: center;
+	width: 100%;
+}
+
+#track-title {
+	font-weight: bold;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+#track-artist {
+	font-size: 0.8rem;
+	opacity: 0.75;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+#track-lyric {
+	font-size: 0.8rem;
+	opacity: 0.75;
+}
+
+/* progress slider and shuffle button alignment */
+#progress {
+	flex: 1;
+}
+
+#shuffle-btn {
+	margin-left: auto;
+}
+
+/* queue table container */
+table {
+	width: 100%;
+	border-collapse: collapse;
+	table-layout: fixed;
+	margin-top: 0.5rem;
+}
+
+/* hint optimization for virtual scroll updates */
+tbody {
+	will-change: contents;
+}
+
+th,
+td {
+	text-align: left;
+	vertical-align: middle;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+/* actions column (6th) in queue table */
+#queue-table td:nth-child(6) {
+	overflow: visible;
+	white-space: normal;
+}
+
+#queue-table td:nth-child(6) button {
+	margin-right: 0.5rem;
+}
+
+#queue-table td:nth-child(6) button:last-child {
+	margin-right: 0;
+}
+
+/* alternating row backgrounds */
+tbody tr.stripe {
+	background: var(--bg-secondary);
+}
+
+/* currently playing track highlighting with pulse animation */
+tbody tr.currently-playing {
+	background: var(--playing);
+	animation: pulse 4s linear infinite;
+}
+
+/* cover art column width */
+#queue-table th:nth-child(1),
+#queue-table td:nth-child(1) {
+	width: calc(var(--art-song) * 2);
+}
+
+/* drag and drop states */
+tbody tr.dragging {
+	opacity: 0.5;
+}
+
+tbody tr.selected {
+	background: var(--selection-color);
+	color: white;
+}
+
+tbody tr.drag-over-above {
+	border-top: 2px solid currentColor;
+	background: var(--bg-secondary);
+}
+
+tbody tr.drag-over-below {
+	border-bottom: 2px solid currentColor;
+	background: var(--bg-secondary);
+}
+
+/* floating context menu for queue actions */
+.context-menu {
+	position: fixed;
+	background: var(--bg-context-menu);
+	backdrop-filter: blur(16px);
+	border: 1px solid var(--border);
+	border-radius: 0.25rem;
+	box-shadow: 0 1px 4px rgba(0, 0, 0, 0.25);
+	z-index: 1000;
+	min-width: 10rem;
+}
+
+.context-menu-item {
+	display: block;
+	width: 100%;
+	padding: 0.25rem 1rem;
+	background: none;
+	border: none;
+	text-align: left;
+}
+
+.context-menu-item:hover {
+	background: Highlight;
+	color: HighlightText;
+}
+
+/* error text color */
+.error {
+	color: var(--error-color);
+}
+
+/* modals (login, settings) */
+.modal {
+	position: fixed;
+	inset: 0;
+	background: rgba(0, 0, 0, 0.75);
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	z-index: 2000;
+}
+
+.modal.hidden {
+	display: none;
+}
+
+.modal-content {
+	background: Menu;
+	border: 1px solid var(--border);
+	padding: 1rem;
+	box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+}
+
+.modal-content h2 {
+	margin-bottom: 1rem;
+}
+
+.modal-content button {
+	margin-top: 1rem;
+	padding: 0.5rem 1rem;
+	border: 1px solid var(--border);
+	border-radius: 0.25rem;
+	background: var(--bg-tertiary);
+}
+
+/* form and settings groups */
+.form-group,
+.settings-group {
+	margin-bottom: 1.5rem;
+}
+
+.form-group label,
+.settings-group label {
+	display: block;
+	margin-bottom: 0.5rem;
+}
+
+.settings-group label {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+}
+
+/* range sliders and checkboxes in settings */
+.settings-group input[type="range"],
+.settings-group input[type="checkbox"] {
+	width: 100%;
+	cursor: pointer;
+}
+
+.settings-group input[type="checkbox"] {
+	width: auto;
+}
+
+#close-settings-btn {
+	width: 100%;
+	padding: 0.5rem;
+	margin-top: 1rem;
+	background: var(--bg-tertiary);
+	border: 1px solid var(--border);
+	border-radius: 0.25rem;
+	cursor: pointer;
+}
+
+#close-settings-btn:hover {
+	background: Highlight;
+	color: HighlightText;
+}

src/css/layout.css

···
+/* main layout grid (desktop: 3 columns, 3 rows) */
+body {
+	height: 100vh;
+	display: grid;
+	grid-template-columns: 20rem 1fr;
+	grid-template-rows: 1fr auto auto;
+	grid-template-areas:
+		"sidebar main"
+		"header header"
+		"footer footer";
+}
+
+/* playback controls (prev, play, next, progress, time display) */
+header {
+	grid-area: header;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	gap: 0.5rem;
+	padding: 0.5rem;
+	border-top: 1px solid var(--border);
+	background: var(--bg-tertiary);
+}
+
+/* library browser and track info panel */
+#sidebar {
+	grid-area: sidebar;
+	border-right: 1px solid var(--border);
+	background: var(--bg-secondary);
+	display: flex;
+	flex-direction: column;
+	min-height: 0;
+}
+
+/* container for tree of artists and playlists */
+#library {
+	flex: 1;
+	overflow-y: auto;
+	min-height: 0;
+	padding-inline: 1rem;
+}
+
+/* song queue table */
+main {
+	grid-area: main;
+	overflow-y: auto;
+	padding-inline: 1rem;
+	-webkit-overflow-scrolling: touch;
+}
+
+/* action buttons and version info */
+footer {
+	grid-area: footer;
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	padding: 0.5rem 1rem;
+	border-top: 1px solid var(--border-subtle);
+	background: var(--bg-tertiary);
+}
+
+/* mobile layout */
+@media (max-width: 768px) {
+	body {
+		grid-template-columns: 1fr;
+		grid-template-rows: 1fr 1fr auto auto;
+		grid-template-areas:
+			"main"
+			"sidebar"
+			"header"
+			"footer";
+	}
+
+	/* hide less important columns on mobile */
+	th:nth-child(3),
+	th:nth-child(4),
+	th:nth-child(5),
+	td:nth-child(3),
+	td:nth-child(4),
+	td:nth-child(5) {
+		display: none;
+	}
+
+	#sidebar {
+		border-right: none;
+		border-top: 1px solid var(--border);
+		overflow: hidden;
+	}
+
+	/* hide now playing cover art on mobile */
+	#now-playing #cover-art {
+		display: none;
+	}
+
+	/* hide button labels on mobile */
+	footer button span {
+		display: none;
+	}
+}

src/index.html

···
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>tinysub</title>
+		<link rel="stylesheet" href="css/base.css" />
+		<link rel="stylesheet" href="css/layout.css" />
+		<link rel="stylesheet" href="css/components.css" />
+		<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
+	</head>
+	<body>
+		<!-- login and authentication -->
+		<div id="auth-modal" class="modal">
+			<div class="modal-content">
+				<h2>tinysub</h2>
+				<form id="login-form">
+					<div class="form-group">
+						<label for="server">server URL:</label>
+						<input
+							type="url"
+							id="server"
+							placeholder="http://localhost:4040"
+							required
+						/>
+					</div>
+					<div class="form-group">
+						<label for="username">username:</label>
+						<input id="username" required />
+					</div>
+					<div class="form-group">
+						<label for="password">password:</label>
+						<input type="password" id="password" required />
+					</div>
+					<button type="submit">connect</button>
+					<p id="auth-error" class="error"></p>
+				</form>
+			</div>
+		</div>
+		<!-- settings panel -->
+		<div id="settings-modal" class="modal hidden">
+			<div class="modal-content">
+				<h2>settings</h2>
+				<div class="settings-group">
+					<label>
+						<input type="checkbox" id="scrobbling-toggle" />
+						enable scrobbling
+					</label>
+				</div>
+				<div class="settings-group">
+					<label
+						>artist art size: <span id="artist-size-display">16</span>px</label
+					>
+					<input
+						type="range"
+						id="artist-size"
+						min="0"
+						max="256"
+						step="4"
+						value="16"
+					/>
+				</div>
+				<div class="settings-group">
+					<label
+						>album art size: <span id="album-size-display">32</span>px</label
+					>
+					<input
+						type="range"
+						id="album-size"
+						min="0"
+						max="256"
+						step="4"
+						value="32"
+					/>
+				</div>
+				<div class="settings-group">
+					<label>song art size: <span id="song-size-display">16</span>px</label>
+					<input
+						type="range"
+						id="song-size"
+						min="0"
+						max="256"
+						step="4"
+						value="16"
+					/>
+				</div>
+				<button id="close-settings-btn">close</button>
+			</div>
+		</div>
+		<header>
+			<audio id="player" crossorigin="anonymous"></audio>
+			<button id="prev-btn" aria-label="previous">
+				<img
+					src="static/famfamfam-silk/control_rewind_blue.png"
+					alt="previous"
+				/>
+			</button>
+			<button id="play-btn" aria-label="play">
+				<img src="static/famfamfam-silk/control_play_blue.png" alt="play" />
+			</button>
+			<button id="next-btn" aria-label="next">
+				<img
+					src="static/famfamfam-silk/control_fastforward_blue.png"
+					alt="next"
+				/>
+			</button>
+			<input type="range" id="progress" min="0" max="100" value="0" />
+			<span id="time-display">0:00 / 0:00</span>
+		</header>
+
+		<aside id="sidebar">
+			<div id="library">
+				<h2>
+					<a class="section-toggle" data-section="artists">▸ artists</a>
+				</h2>
+				<div id="artists-tree"></div>
+				<h2>
+					<a class="section-toggle" data-section="playlists">▸ playlists</a>
+				</h2>
+				<div id="playlists-tree"></div>
+			</div>
+			<div id="now-playing">
+				<img
+					id="cover-art"
+					src="static/subsonic.png"
+					alt="cover"
+					loading="lazy"
+				/>
+				<div id="track-info">
+					<div id="track-title">no track playing</div>
+					<div id="track-artist"></div>
+					<div id="track-lyric"></div>
+				</div>
+			</div>
+		</aside>
+
+		<main>
+			<table id="queue-table">
+				<thead>
+					<tr>
+						<th></th>
+						<th>title</th>
+						<th>artist</th>
+						<th>album</th>
+						<th>duration</th>
+						<th><span id="queue-count">0</span> songs</th>
+					</tr>
+				</thead>
+				<tbody id="queue-list"></tbody>
+			</table>
+			<div id="background-cover"></div>
+		</main>
+
+		<footer>
+			<div>tinysub 1.0.0</div>
+			<button id="shuffle-btn" aria-label="shuffle">
+				<img
+					src="static/famfamfam-silk/arrow_refresh_small.png"
+					alt="shuffle"
+				/>
+				<span>shuffle all</span>
+			</button>
+			<button id="clear-btn" aria-label="clear">
+				<img src="static/famfamfam-silk/cross.png" alt="clear" />
+				<span>clear all</span>
+			</button>
+			<button id="settings-btn" aria-label="settings">
+				<img src="static/famfamfam-silk/cog.png" alt="settings" />
+				<span>settings</span>
+			</button>
+			<button id="logout-btn" aria-label="logout">
+				<img src="static/famfamfam-silk/door_out.png" alt="logout" />
+				<span>logout</span>
+			</button>
+		</footer>
+
+		<script src="js/constants.js"></script>
+		<script src="js/utils.js"></script>
+		<script src="js/validation.js"></script>
+
+		<script src="js/selection-manager.js"></script>
+
+		<script src="js/api.js"></script>
+		<script src="js/state.js"></script>
+		<script src="js/settings.js"></script>
+		<script src="js/queue.js"></script>
+		<script src="js/library.js"></script>
+		<script src="js/ui.js"></script>
+		<script src="js/auth.js"></script>
+		<script src="js/player.js"></script>
+		<script src="js/draggable.js"></script>
+		<script src="js/contextmenu.js"></script>
+		<script src="js/lyrics.js"></script>
+		<script src="js/events.js"></script>
+	</body>
+</html>

src/js/api.js

···
+// subsonic api client for server communication
+class SubsonicAPI {
+	constructor(serverUrl, username, password) {
+		this.serverUrl = serverUrl.replace(/\/$/, "");
+		this.username = username;
+		this.password = password;
+		this.clientName = "tinysub";
+		this.apiVersion = "1.12.0";
+		this.requestTimeout = 30000;
+	}
+
+	// generate random salt and hashed password for auth
+	getAuthParams() {
+		const salt = Math.random().toString(36).substring(7);
+		const token = CryptoJS.MD5(this.password + salt).toString();
+		return {
+			u: this.username,
+			t: token,
+			s: salt,
+			c: this.clientName,
+			v: this.apiVersion,
+		};
+	}
+
+	// build authenticated REST API URL with params
+	_buildAuthUrl(method, params = {}) {
+		return `${this.serverUrl}/rest/${method}?${new URLSearchParams({
+			...this.getAuthParams(),
+			...params,
+		})}`;
+	}
+
+	// make request to subsonic rest api with error handling
+	async request(method, params = {}) {
+		if (!method || typeof method !== "string" || method.trim().length === 0) {
+			throw new Error("API method is required");
+		}
+
+		const queryParams = new URLSearchParams({
+			...this.getAuthParams(),
+			f: "json",
+			...params,
+		});
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.requestTimeout);
+
+		try {
+			const response = await fetch(
+				`${this.serverUrl}/rest/${method}?${queryParams}`,
+				{ signal: controller.signal },
+			);
+			const data = await response.json();
+
+			if (data["subsonic-response"].status === "ok") {
+				return data["subsonic-response"];
+			}
+			throw new Error(data["subsonic-response"].error?.message || "API error");
+		} catch (error) {
+			if (error.name === "AbortError") {
+				throw new Error(`Request timeout after ${this.requestTimeout / 1000}s`);
+			}
+			throw new Error(`Request failed: ${error.message}`);
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+
+	ping() {
+		return this.request("ping.view");
+	}
+
+	getIndexes() {
+		return this.request("getIndexes.view");
+	}
+
+	_validateAndRequest(id, method, params, context) {
+		const validation = validateId(id, context);
+		if (!validation.valid) throw new Error(validation.error);
+		return this.request(method, { ...params, id });
+	}
+
+	getArtist(id) {
+		return this._validateAndRequest(id, "getArtist.view", {}, "Artist ID");
+	}
+
+	getAlbum(id) {
+		return this._validateAndRequest(id, "getAlbum.view", {}, "Album ID");
+	}
+
+	getPlaylists() {
+		return this.request("getPlaylists.view");
+	}
+
+	getPlaylist(id) {
+		return this._validateAndRequest(id, "getPlaylist.view", {}, "Playlist ID");
+	}
+
+	getStreamUrl(id) {
+		const validation = validateId(id, "Stream ID");
+		if (!validation.valid) throw new Error(validation.error);
+		return this._buildAuthUrl("stream.view", { id });
+	}
+
+	getCoverArtUrl(id, size = 64) {
+		const validation = validateId(id, "Cover Art ID");
+		if (!validation.valid) throw new Error(validation.error);
+		return this._buildAuthUrl("getCoverArt.view", { id, size });
+	}
+
+	scrobble(id) {
+		return this._validateAndRequest(
+			id,
+			"scrobble.view",
+			{ submission: true },
+			"Scrobble ID",
+		);
+	}
+
+	getStarred2() {
+		return this.request("getStarred2.view");
+	}
+
+	star(id) {
+		return this._validateAndRequest(id, "star.view", {}, "Song ID");
+	}
+
+	unstar(id) {
+		return this._validateAndRequest(id, "unstar.view", {}, "Song ID");
+	}
+
+	getLyricsBySongId(id) {
+		return this._validateAndRequest(
+			id,
+			"getLyricsBySongId.view",
+			{},
+			"Song ID",
+		);
+	}
+
+	getLyrics(artist, title) {
+		if (!artist || !title) {
+			throw new Error("Artist and title are required for getLyrics");
+		}
+		return this.request("getLyrics.view", { artist, title });
+	}
+}

src/js/auth.js

···
+// credential manager with fallback handling
+const CredentialManager = {
+	save: (server, username, password) => {
+		localStorage.setItem(
+			"tinysub_credentials",
+			JSON.stringify({ server, username, password }),
+		);
+	},
+	load: () => {
+		try {
+			const saved = localStorage.getItem("tinysub_credentials");
+			return saved
+				? JSON.parse(saved)
+				: { server: "", username: "", password: "" };
+		} catch {
+			// fallback to old format if atomic json fails
+			return {
+				server: localStorage.getItem("tinysub_server") || "",
+				username: localStorage.getItem("tinysub_username") || "",
+				password: localStorage.getItem("tinysub_password") || "",
+			};
+		}
+	},
+};
+
+// load library, playlists, and favorites after successful login
+async function initializeApp() {
+	toggleAuthModal(false);
+	await loadLibrary();
+	await loadPlaylists();
+	await loadFavorites();
+}
+
+// handle login form submission with validation
+async function handleLogin() {
+	if (handleLogin.isInProgress) return;
+
+	const server = ui.serverInput.value;
+	const username = ui.usernameInput.value;
+	const password = ui.passwordInput.value;
+
+	ui.authError.textContent = "";
+
+	const urlValidation = validateServerUrl(server);
+	if (!urlValidation.valid) {
+		ui.authError.textContent = urlValidation.error;
+		return;
+	}
+
+	const credValidation = validateCredentials(username, password);
+	if (!credValidation.valid) {
+		ui.authError.textContent = credValidation.error;
+		return;
+	}
+
+	handleLogin.isInProgress = true;
+	const {
+		value: { username: validUsername, password: validPassword },
+	} = credValidation;
+	const validServerUrl = urlValidation.value;
+
+	try {
+		state.api = new SubsonicAPI(validServerUrl, validUsername, validPassword);
+		// test connection and initialize app
+		await state.api.ping();
+		CredentialManager.save(validServerUrl, validUsername, validPassword);
+		await initializeApp();
+	} catch (error) {
+		ui.authError.textContent = `${MESSAGES.CONNECTION_ERROR} ${error.message}`;
+		state.api = null;
+	} finally {
+		handleLogin.isInProgress = false;
+	}
+}
+handleLogin.isInProgress = false;
+
+// clear localStorage and reload to logout
+function handleLogout() {
+	localStorage.clear();
+	location.reload();
+}

src/js/constants.js

···
+// constants
+
+const CLASSES = {
+	SELECTED: "selected",
+	DRAGGING: "dragging",
+	DRAG_OVER_ABOVE: "drag-over-above",
+	DRAG_OVER_BELOW: "drag-over-below",
+	CURRENTLY_PLAYING: "currently-playing",
+	CONTEXT_MENU: "context-menu",
+	CONTEXT_MENU_ITEM: "context-menu-item",
+	TREE_TOGGLE: "tree-toggle",
+	TREE_NAME: "tree-name",
+	TREE_ITEM: "tree-item",
+	NESTED: "nested",
+	NESTED_SONGS: "nested-songs",
+	QUEUE_ACTION: "queue-action",
+	QUEUE_FAVORITE: "queue-favorite",
+	QUEUE_PLAY_NEXT: "queue-play-next",
+	QUEUE_MOVE_UP: "queue-move-up",
+	QUEUE_MOVE_DOWN: "queue-move-down",
+	QUEUE_REMOVE: "queue-remove",
+	QUEUE_COVER: "queue-cover",
+	FAVORITED: "favorited",
+	ERROR: "error",
+	DISABLED: "disabled",
+};
+
+const DATA_ATTRS = {
+	INDEX: "data-index",
+};
+
+const DOM_IDS = {
+	AUTH_MODAL: "auth-modal",
+	LOGIN_FORM: "login-form",
+	QUEUE_TABLE: "queue-table",
+	AUTH_ERROR: "auth-error",
+	SERVER_INPUT: "server",
+	USERNAME_INPUT: "username",
+	PASSWORD_INPUT: "password",
+	LIBRARY_TREE: "artists-tree",
+	PLAYLISTS_TREE: "playlists-tree",
+	QUEUE_LIST: "queue-list",
+	QUEUE_COUNT: "queue-count",
+	COVER_ART: "cover-art",
+	BACKGROUND_COVER: "background-cover",
+	TRACK_TITLE: "track-title",
+	TRACK_ARTIST: "track-artist",
+	TRACK_LYRIC: "track-lyric",
+	PLAYER: "player",
+	PLAY_BTN: "play-btn",
+	PREV_BTN: "prev-btn",
+	NEXT_BTN: "next-btn",
+	PROGRESS: "progress",
+	TIME_DISPLAY: "time-display",
+	LOGOUT_BTN: "logout-btn",
+	SHUFFLE_BTN: "shuffle-btn",
+	CLEAR_BTN: "clear-btn",
+	SECTION_TOGGLE: "section-toggle",
+};
+
+const MESSAGES = {
+	NO_TRACK_PLAYING: "no track playing",
+	PLAYBACK_FINISHED: "playback finished",
+	NO_ARTISTS: "no artists",
+	NO_PLAYLISTS: "no playlists",
+	CONNECTION_ERROR: "connection failed:",
+};
+
+const ICONS = {
+	PLAY: "static/famfamfam-silk/control_play_blue.png",
+	PAUSE: "static/famfamfam-silk/control_pause_blue.png",
+	PREV: "static/famfamfam-silk/control_rewind_blue.png",
+	NEXT: "static/famfamfam-silk/control_fastforward_blue.png",
+	PLAY_NEXT: "static/famfamfam-silk/control_fastforward_blue.png",
+	ADD: "static/famfamfam-silk/add.png",
+	FAVORITE: "static/famfamfam-silk/heart.png",
+	MOVE_UP: "static/famfamfam-silk/arrow_up.png",
+	MOVE_DOWN: "static/famfamfam-silk/arrow_down.png",
+	REMOVE: "static/famfamfam-silk/cross.png",
+};

src/js/contextmenu.js

···
+let contextMenuEl = null;
+let currentHideMenuHandler = null;
+
+// remove context menu
+function cleanupContextMenu() {
+	if (contextMenuEl) {
+		contextMenuEl.remove();
+		contextMenuEl = null;
+	}
+	if (currentHideMenuHandler) {
+		["click", "contextmenu"].forEach((event) =>
+			document.removeEventListener(event, currentHideMenuHandler, {
+				capture: true,
+			}),
+		);
+		currentHideMenuHandler = null;
+	}
+}
+
+// display context menu with given items at position
+function showContextMenu(x, y, items) {
+	cleanupContextMenu();
+
+	contextMenuEl = createElement("div", {
+		className: CLASSES.CONTEXT_MENU,
+		attributes: {
+			style: `left: ${Math.min(x, window.innerWidth - 200)}px; top: ${Math.min(y, window.innerHeight - 200)}px;`,
+		},
+	});
+
+	Object.entries(items).forEach(([label, handler]) => {
+		const item = createElement("button", {
+			className: CLASSES.CONTEXT_MENU_ITEM,
+			textContent: label,
+			listeners: { click: handler },
+		});
+		contextMenuEl.appendChild(item);
+	});
+
+	document.body.appendChild(contextMenuEl);
+
+	currentHideMenuHandler = cleanupContextMenu;
+
+	["click", "contextmenu"].forEach((event) =>
+		document.addEventListener(event, currentHideMenuHandler, { capture: true }),
+	);
+}
+
+// setup right-click context menu for queue table
+function setupQueueContextMenu() {
+	ui.queueList.addEventListener("contextmenu", (e) => {
+		const row = getClosestRow(e.target);
+		if (!row) return;
+
+		e.preventDefault();
+		const idx = getRowIndex(row, DATA_ATTRS.INDEX);
+
+		if (!selectionManager.isSelected(idx)) {
+			selectionManager.select(idx);
+		}
+
+		const selectedIndices = Array.from(selectionManager.getSelected());
+
+		showContextMenu(e.clientX, e.clientY, {
+			Play: () => {
+				state.queueIndex = selectedIndices[0];
+				playTrack(state.queue[selectedIndices[0]]);
+				updateQueue(false);
+			},
+			"Play Next": () => {
+				const insertPos = state.queueIndex >= 0 ? state.queueIndex + 1 : 0;
+				moveQueueItems(
+					state.queue,
+					selectedIndices,
+					insertPos,
+					getQueueCallbacks(),
+				);
+			},
+			Favorite: async () => {
+				await Promise.all(
+					selectedIndices.map((i) => setFavoriteSong(state.queue[i], true)),
+				);
+				updateQueueDisplay();
+			},
+			Unfavorite: async () => {
+				await Promise.all(
+					selectedIndices.map((i) => setFavoriteSong(state.queue[i], false)),
+				);
+				updateQueueDisplay();
+			},
+			"Move Up": () => {
+				const firstIdx = Math.min(...selectedIndices);
+				if (firstIdx > 0) {
+					moveQueueItems(
+						state.queue,
+						selectedIndices,
+						firstIdx - 1,
+						getQueueCallbacks(),
+					);
+				}
+			},
+			"Move Down": () => {
+				const lastIdx = Math.max(...selectedIndices);
+				if (lastIdx < state.queue.length - 1) {
+					moveQueueItems(
+						state.queue,
+						selectedIndices,
+						lastIdx + 2,
+						getQueueCallbacks(),
+					);
+				}
+			},
+			Delete: removeSelectedRows,
+		});
+	});
+
+	document.addEventListener(
+		"contextmenu",
+		(e) => {
+			const isQueueTable = e.target.closest(`#${DOM_IDS.QUEUE_TABLE}`);
+
+			if (contextMenuEl && isQueueTable) {
+				contextMenuEl.remove();
+				contextMenuEl = null;
+				return;
+			}
+
+			if (!isQueueTable || contextMenuEl) {
+				e.preventDefault();
+				e.stopImmediatePropagation();
+			}
+		},
+		true,
+	);
+}

src/js/draggable.js

···
+// setup drag and drop for queue reordering
+function setupDragAndDrop() {
+	const clearDragOver = () =>
+		clearRowClasses(ui.queueList, "tr:not(.virtual-spacer)", [
+			CLASSES.DRAG_OVER_ABOVE,
+			CLASSES.DRAG_OVER_BELOW,
+			CLASSES.DRAGGING,
+		]);
+	const isDraggable = (row) =>
+		row &&
+		!row.classList.contains(CLASSES.DRAGGING) &&
+		!row.classList.contains("virtual-spacer");
+	const isDropBelowCenter = (e, row) =>
+		e.clientY - row.getBoundingClientRect().top > row.offsetHeight / 2;
+
+	ui.queueList.addEventListener("dragstart", (e) => {
+		const row = getClosestRow(e.target);
+		if (!row || selectionManager.isSelected(getRowIndex(row, DATA_ATTRS.INDEX)))
+			return;
+
+		clearSelection();
+		selectRow(getRowIndex(row, DATA_ATTRS.INDEX));
+		updateSelectionUI();
+		updateRowClass(ui.queueList, getSelectedIndices(), CLASSES.DRAGGING, true);
+		e.dataTransfer.effectAllowed = "move";
+		e.dataTransfer.setDragImage(row, 0, 0);
+	});
+
+	// handle drag over - show drop indicator
+	ui.queueList.addEventListener("dragover", (e) => {
+		e.preventDefault();
+		e.dataTransfer.dropEffect = "move";
+		const row = getClosestRow(e.target);
+		if (!isDraggable(row)) return;
+
+		clearRowClasses(ui.queueList, "tr:not(.virtual-spacer)", [
+			CLASSES.DRAG_OVER_ABOVE,
+			CLASSES.DRAG_OVER_BELOW,
+		]);
+		row.classList.add(
+			isDropBelowCenter(e, row)
+				? CLASSES.DRAG_OVER_BELOW
+				: CLASSES.DRAG_OVER_ABOVE,
+		);
+	});
+
+	// handle drop and complete the move
+	ui.queueList.addEventListener("drop", (e) => {
+		e.preventDefault();
+		const row = getClosestRow(e.target);
+		if (!isDraggable(row)) return;
+
+		clearDragOver();
+		const draggedIdx = getRowIndex(row, DATA_ATTRS.INDEX);
+		moveQueueItems(
+			state.queue,
+			getSelectedIndices(),
+			isDropBelowCenter(e, row) ? draggedIdx + 1 : draggedIdx,
+			getQueueCallbacks(),
+		);
+	});
+
+	// cleanup on drag end
+	ui.queueList.addEventListener("dragend", clearDragOver);
+}

src/js/events.js

···
+let selectionManager;
+
+// queue operation callbacks for use in move/modification handlers
+const getQueueCallbacks = () => ({
+	onSelectionChange: (newIndices) => selectionManager.setSelection(newIndices),
+	onQueueChange: () => updateQueueDisplay(),
+});
+
+// map button classes to handler functions
+const QUEUE_BUTTON_HANDLERS = {
+	// handler for action buttons (play, move, remove, favorite) on queue rows
+	[CLASSES.QUEUE_ACTION]: (idx) => {
+		state.queueIndex = idx;
+		playTrack(state.queue[state.queueIndex]);
+		updateQueue(false);
+	},
+	[CLASSES.QUEUE_PLAY_NEXT]: (idx) => {
+		const insertPos = state.queueIndex >= 0 ? state.queueIndex + 1 : 0;
+		moveQueueItems(state.queue, [idx], insertPos, getQueueCallbacks());
+	},
+	[CLASSES.QUEUE_MOVE_UP]: (idx) => {
+		const newIdx = idx - 1;
+		if (newIdx >= 0 && newIdx < state.queue.length) {
+			moveQueueItems(state.queue, [idx], newIdx, getQueueCallbacks());
+		}
+	},
+	[CLASSES.QUEUE_MOVE_DOWN]: (idx) => {
+		const newIdx = idx + 1;
+		if (newIdx >= 0 && newIdx < state.queue.length) {
+			moveQueueItems(state.queue, [idx], newIdx + 1, getQueueCallbacks());
+		}
+	},
+	[CLASSES.QUEUE_REMOVE]: (idx) => {
+		state.queue.splice(idx, 1);
+		updateQueue();
+	},
+	[CLASSES.QUEUE_FAVORITE]: async (idx) => {
+		const song = state.queue[idx];
+		if (song) {
+			await setFavoriteSong(song);
+			updateQueueDisplay();
+		}
+	},
+};
+
+// setup media control handlers for hardware buttons and lock screen
+function setupMediaSessionHandlers() {
+	if (!navigator.mediaSession) return;
+
+	const handlers = {
+		play: () => ui.player.play(),
+		pause: () => ui.player.pause(),
+		previoustrack: previousTrack,
+		nexttrack: nextTrack,
+		seekto: (e) => (ui.player.currentTime = e.seekTime),
+	};
+
+	Object.entries(handlers).forEach(([action, handler]) =>
+		navigator.mediaSession.setActionHandler(action, handler),
+	);
+}
+
+document.addEventListener("DOMContentLoaded", async () => {
+	// initialize selection manager for queue table
+	selectionManager = new SelectionManager(ui.queueList, {
+		rowSelector: "tr",
+		indexAttribute: DATA_ATTRS.INDEX,
+		selectedClass: CLASSES.SELECTED,
+	});
+
+	// setup settings modal
+	setupSettings();
+
+	ui.loginForm.addEventListener("submit", (e) => {
+		e.preventDefault();
+		handleLogin();
+	});
+	ui.logoutBtn.addEventListener("click", handleLogout);
+
+	// setup audio element event listeners
+	["play", "pause"].forEach((event) =>
+		ui.player.addEventListener(event, updatePlayIcon),
+	);
+	ui.player.addEventListener("ended", handleTrackEnd);
+	ui.player.addEventListener("loadedmetadata", () => {
+		ui.progress.max = ui.player.duration;
+	});
+	ui.player.addEventListener("timeupdate", () => {
+		ui.progress.value = ui.player.currentTime;
+		const current = formatDuration(ui.player.currentTime);
+		const total = formatDuration(ui.player.duration || 0);
+		ui.timeDisplay.textContent = `${current} / ${total}`;
+		updateMediaSessionPosition();
+		updateLyricDisplay(ui.player.currentTime);
+	});
+
+	// helper to check if queue has a valid current track
+	const hasValidTrack = () =>
+		isValidQueueIndex(state.queueIndex, state.queue.length);
+
+	ui.playBtn.addEventListener("click", () => {
+		if (hasValidTrack()) {
+			if (ui.player.src) {
+				ui.player.paused ? ui.player.play() : ui.player.pause();
+			} else {
+				playTrack(state.queue[state.queueIndex]);
+			}
+		} else if (state.queue.length > 0) {
+			state.queueIndex = 0;
+			playTrack(state.queue[0]);
+			updateQueue(false);
+		}
+	});
+	ui.prevBtn.addEventListener("click", previousTrack);
+	ui.nextBtn.addEventListener("click", nextTrack);
+
+	const handleProgressSeek = (e) => {
+		ui.player.currentTime = parseFloat(e.target.value);
+	};
+	["input", "change"].forEach((event) =>
+		ui.progress.addEventListener(event, handleProgressSeek),
+	);
+
+	// shuffle button, preserve current track position during shuffle
+	ui.shuffleBtn.addEventListener("click", () => {
+		const currentTrack = hasValidTrack() ? state.queue[state.queueIndex] : null;
+		shuffleQueue();
+		if (currentTrack) {
+			state.queueIndex = state.queue.indexOf(currentTrack);
+			updateQueue(false);
+		}
+	});
+	ui.clearBtn.addEventListener("click", () => {
+		clearQueue();
+		resetPlayerUI();
+	});
+	// queue table interactions
+	ui.queueList.addEventListener("click", (e) => {
+		const btn = e.target.closest("button");
+		if (!btn) {
+			// handle row selection on click
+			const row = getClosestRow(e.target);
+			if (row) {
+				const idx = getRowIndex(row, DATA_ATTRS.INDEX);
+				const isMulti = e.ctrlKey || e.metaKey;
+				const isShift = e.shiftKey;
+				selectRow(idx, isMulti, isShift);
+			}
+			return;
+		}
+
+		const row = getClosestRow(btn);
+		const idx = getRowIndex(row, DATA_ATTRS.INDEX);
+
+		for (const [className, handler] of Object.entries(QUEUE_BUTTON_HANDLERS)) {
+			if (btn.classList.contains(className)) {
+				handler(idx);
+				break;
+			}
+		}
+	});
+
+	// double click to play
+	ui.queueList.addEventListener("dblclick", (e) => {
+		const row = getClosestRow(e.target);
+		if (row) {
+			const idx = getRowIndex(row, DATA_ATTRS.INDEX);
+			state.queueIndex = idx;
+			saveQueue();
+			playTrack(state.queue[idx]);
+		}
+	});
+
+	// deselect when clicking outside queue table
+	document.addEventListener("click", (e) => {
+		if (
+			!e.target.closest(`#${DOM_IDS.QUEUE_TABLE}`) &&
+			!e.target.closest(".context-menu")
+		) {
+			clearSelection();
+		}
+	});
+
+	ui.sectionToggles.forEach((toggle) =>
+		toggle.addEventListener("click", handleSectionToggle),
+	);
+
+	// register event handlers and restore previous state
+	setupDragAndDrop();
+	setupQueueContextMenu();
+	// initialize media session once
+	setupMediaSessionHandlers();
+
+	// restore auto-login if credentials saved
+	const credentials = CredentialManager.load();
+	if (credentials.server && credentials.username && credentials.password) {
+		state.api = new SubsonicAPI(
+			credentials.server,
+			credentials.username,
+			credentials.password,
+		);
+		loadQueue();
+		updateQueueDisplay();
+		await initializeApp();
+		// restore song display after init
+		if (state.queueIndex >= 0 && state.queueIndex < state.queue.length) {
+			playTrack(state.queue[state.queueIndex]);
+			ui.player.pause();
+		}
+	} else {
+		toggleAuthModal(true);
+	}
+});

src/js/library.js

···
+const playNextByType = {
+	artist: (id) =>
+		addToQueue(() => state.api.getArtist(id), SONG_EXTRACTORS.artist, true),
+	album: (id) =>
+		addToQueue(() => state.api.getAlbum(id), SONG_EXTRACTORS.album, true),
+	playlist: (id) =>
+		addToQueue(() => state.api.getPlaylist(id), SONG_EXTRACTORS.playlist, true),
+	song: (song) =>
+		addToQueue(() => Promise.resolve(song), SONG_EXTRACTORS.song, true),
+};
+
+async function loadData(config) {
+	const { fetcher, transformer, stateKey, renderFn } = config;
+	const data = await fetcher();
+	state[stateKey] = transformer(data);
+	renderFn();
+}
+
+async function loadLibrary() {
+	return loadData({
+		fetcher: () => state.api.getIndexes(),
+		transformer: (data) =>
+			data.indexes?.index?.flatMap((idx) => idx.artist || []) || [],
+		stateKey: "library",
+		renderFn: renderLibraryTree,
+	});
+}
+
+async function loadPlaylists() {
+	return loadData({
+		fetcher: () => state.api.getPlaylists(),
+		transformer: (data) => data.playlist || data.playlists?.playlist || [],
+		stateKey: "playlists",
+		renderFn: renderPlaylistsTree,
+	});
+}
+
+async function loadFavorites() {
+	const data = await state.api.getStarred2();
+	const songs = data.starred2?.song || data.song || [];
+	state.favorites.clear();
+	songs.forEach((song) => state.favorites.add(song.id));
+	updateQueueDisplay();
+}
+
+function renderTree(config) {
+	const {
+		container,
+		expandedKey,
+		items,
+		emptyMessage,
+		itemMapper,
+		onToggle,
+		onAction,
+		onPlayNext,
+		artType,
+	} = config;
+
+	container.innerHTML = "";
+	if (!state.expanded[expandedKey]) return;
+	if (!items.length) {
+		container.innerHTML = `<div class="item">${emptyMessage}</div>`;
+		return;
+	}
+
+	const ul = createElement("ul");
+	items.forEach((item) => {
+		const mapped = itemMapper(item);
+		const li = createTreeItem(
+			mapped.label,
+			mapped.cover || null,
+			onToggle ? (li) => onToggle(item, li) : null,
+			() => onAction(item),
+			onPlayNext ? () => onPlayNext(item) : null,
+			artType,
+			item.id,
+		);
+		ul.appendChild(li);
+	});
+	container.appendChild(ul);
+}
+
+async function loadAndRenderItems(config) {
+	const {
+		fetcher,
+		itemExtractor,
+		parentLi,
+		ulClassName,
+		itemMapper,
+		onToggle,
+		onAction,
+		onPlayNext,
+		onExpanded,
+		artType,
+	} = config;
+	try {
+		const data = await fetcher();
+		const items = itemExtractor(data);
+		if (!items.length) return;
+
+		const ul = createElement("ul", { className: ulClassName });
+		items.forEach((item) => {
+			const mapped = itemMapper(item);
+			const li = createTreeItem(
+				mapped.label,
+				mapped.cover || null,
+				onToggle ? (li) => onToggle(item, li) : null,
+				() => onAction(item),
+				onPlayNext ? () => onPlayNext(item) : null,
+				artType,
+				item.id,
+			);
+			ul.appendChild(li);
+			if (onExpanded && mapped.isExpanded) onExpanded(item, li);
+		});
+		parentLi.appendChild(ul);
+	} catch (error) {
+		// silently handle load errors
+	}
+}
+
+async function loadAndRenderAlbums(artistId, parentLi) {
+	return loadAndRenderItems({
+		fetcher: () => state.api.getArtist(artistId),
+		itemExtractor: (data) => data.artist?.album || [],
+		parentLi,
+		ulClassName: CLASSES.NESTED,
+		artType: "artAlbum",
+		itemMapper: (album) => ({
+			label: album.name,
+			cover: shouldShowArt("artAlbum", album.coverArt),
+			isExpanded: state.expanded.items.albums[album.id],
+		}),
+		onToggle: (album, li) => {
+			state.expanded.items.albums[album.id] =
+				!state.expanded.items.albums[album.id];
+			// clear any existing songs before toggling
+			li.querySelector(`ul.${CLASSES.NESTED_SONGS}`)?.remove();
+			if (state.expanded.items.albums[album.id]) {
+				loadAndRenderSongs(album.id, li);
+			}
+		},
+		onExpanded: (album, li) => loadAndRenderSongs(album.id, li),
+		onAction: (album) => addAlbumToQueue(album.id),
+		onPlayNext: (album) => playNextByType.album(album.id),
+	});
+}
+
+async function loadAndRenderSongs(albumId, parentLi) {
+	return loadAndRenderItems({
+		fetcher: () => state.api.getAlbum(albumId),
+		itemExtractor: (data) => data.album?.song || [],
+		parentLi,
+		ulClassName: CLASSES.NESTED_SONGS,
+		artType: "artSong",
+		itemMapper: (song) => ({
+			label: song.title,
+		}),
+		onAction: (song) => addSongToQueue(song),
+		onPlayNext: (song) => playNextByType.song(song),
+	});
+}
+
+function renderLibraryTree() {
+	renderTree({
+		container: ui.artistsTree,
+		expandedKey: "artists",
+		items: state.library,
+		emptyMessage: MESSAGES.NO_ARTISTS,
+		artType: "artArtist",
+		itemMapper: (artist) => ({
+			label: artist.title || artist.name,
+			cover: shouldShowArt("artArtist", artist.coverArt),
+		}),
+		onToggle: (artist, li) => {
+			state.expanded.items.artists[artist.id] =
+				!state.expanded.items.artists[artist.id];
+			// clear any existing albums before toggling
+			li.querySelector(`ul.${CLASSES.NESTED}`)?.remove();
+			if (state.expanded.items.artists[artist.id]) {
+				loadAndRenderAlbums(artist.id, li);
+			}
+		},
+		onAction: (artist) => addArtistToQueue(artist.id),
+		onPlayNext: (artist) => playNextByType.artist(artist.id),
+	});
+
+	// restore expanded artists after re-render
+	restoreExpandedItems(
+		state.library,
+		state.expanded.items.artists,
+		ui.artistsTree,
+	);
+}
+
+function restoreExpandedItems(items, expandedMap, container) {
+	items.forEach((item) => {
+		if (expandedMap[item.id]) {
+			const li = container.querySelector(`li[data-item-id="${item.id}"]`);
+			if (li && !li.querySelector(`ul.${CLASSES.NESTED}`)) {
+				loadAndRenderAlbums(item.id, li);
+			}
+		}
+	});
+}
+
+function renderPlaylistsTree() {
+	renderTree({
+		container: ui.playlistsTree,
+		expandedKey: "playlists",
+		items: state.playlists,
+		emptyMessage: MESSAGES.NO_PLAYLISTS,
+		artType: "artArtist",
+		itemMapper: (playlist) => ({
+			label: playlist.name,
+			cover: null,
+		}),
+		onToggle: null,
+		onAction: (playlist) => addPlaylistToQueue(playlist.id),
+		onPlayNext: (playlist) => playNextByType.playlist(playlist.id),
+	});
+}

src/js/lyrics.js

···
+let currentLyrics = [];
+
+function parseLineArray(lines, timeField = "time", forceZeroTime = false) {
+	if (!Array.isArray(lines)) return [];
+	return lines
+		.map((line) => {
+			const text = (line.value || "").trim();
+			if (text) {
+				const timeMs = forceZeroTime ? 0 : parseInt(line[timeField]) || 0;
+				return { time: timeMs / 1000, text };
+			}
+		})
+		.filter(Boolean)
+		.sort((a, b) => a.time - b.time);
+}
+
+function parseLyrics(input) {
+	if (!input) return [];
+
+	const lines =
+		typeof input === "string" ? input.split("\n") : input.line ? [input] : [];
+	const parsed = [];
+
+	for (const line of lines) {
+		const lrcMatch = line.match?.(/\[(\d+):(\d+)\.(\d+)\](.*)/);
+		if (lrcMatch) {
+			const [_, m, s, ms, text] = lrcMatch;
+			const time = parseInt(m) * 60 + parseInt(s) + parseInt(ms) / 1000;
+			if (text.trim()) parsed.push({ time, text: text.trim() });
+		}
+	}
+
+	if (parsed.length === 0 && typeof input === "string" && input.trim()) {
+		return [{ time: 0, text: input.trim() }];
+	}
+
+	return parsed.sort((a, b) => a.time - b.time);
+}
+
+function parseStructured(array) {
+	if (!Array.isArray(array)) return [];
+	for (const entry of array) {
+		if (entry.line?.length) {
+			const parsed = parseLineArray(entry.line, "start", !entry.synced);
+			if (parsed.length > 0) return parsed;
+		}
+	}
+	return [];
+}
+
+function getCurrentLyric(currentTime) {
+	if (!currentLyrics.length) return null;
+	for (let i = currentLyrics.length - 1; i >= 0; i--) {
+		if (currentLyrics[i].time <= currentTime) return currentLyrics[i];
+	}
+	return null;
+}
+
+// fetch and display lyrics for current song
+async function loadLyricsForSong(song) {
+	if (!song || !state.api) return;
+
+	try {
+		if (song.id) {
+			const response = await state.api.getLyricsBySongId(song.id);
+			const structuredArray = response.lyricsList?.structuredLyrics;
+			if (structuredArray) {
+				currentLyrics = parseStructured(structuredArray);
+				updateLyricDisplay(ui.player.currentTime);
+				return;
+			}
+		}
+
+		if (song.artist && song.title) {
+			const response = await state.api.getLyrics(song.artist, song.title);
+			currentLyrics = parseLyrics(response.lyrics.value || response.lyrics);
+			updateLyricDisplay(ui.player.currentTime);
+		}
+	} catch {
+		currentLyrics = [];
+		ui.trackLyric.textContent = "";
+	}
+}
+
+function updateLyricDisplay(currentTime) {
+	const lyric = getCurrentLyric(currentTime);
+	ui.trackLyric.textContent = lyric ? `♪ ${lyric.text}` : "";
+}
+
+function clearLyrics() {
+	currentLyrics = [];
+	ui.trackLyric.textContent = "";
+}

src/js/player.js

···
+// load and play a song
+function playTrack(song) {
+	if (!song) {
+		resetPlayerUI();
+		return;
+	}
+
+	ui.trackTitle.textContent = song.title || "Unknown";
+	ui.trackArtist.textContent = song.artist || "Unknown Artist";
+	setCoverArt(song);
+	ui.player.src = state.api.getStreamUrl(song.id);
+	ui.player.play();
+	loadLyricsForSong(song);
+	highlightCurrentTrack();
+	updateMediaSession(song);
+}
+
+// set cover art in player UI and background
+function setCoverArt(song) {
+	const backgroundCover = document.getElementById(DOM_IDS.BACKGROUND_COVER);
+	if (song?.coverArt) {
+		const coverUrl = state.api.getCoverArtUrl(song.coverArt, 512);
+		ui.coverArt.src = coverUrl;
+		if (backgroundCover)
+			backgroundCover.style.backgroundImage = `url('${coverUrl}')`;
+	} else {
+		ui.coverArt.src = "";
+		if (backgroundCover) backgroundCover.style.backgroundImage = "";
+	}
+}
+
+// move to next or previous track in queue
+function navigateTrack(offset) {
+	const newIndex = state.queueIndex + offset;
+	if (newIndex >= 0 && newIndex < state.queue.length) {
+		state.queueIndex = newIndex;
+		saveQueue();
+		playTrack(state.queue[state.queueIndex]);
+	}
+}
+
+const previousTrack = () => navigateTrack(-1);
+const nextTrack = () => navigateTrack(1);
+
+// toggle favorite status of a song
+const setFavoriteSong = async (song, force) => {
+	if (!song || !state.api) return;
+	const isFavorited = state.favorites.has(song.id);
+	const shouldAdd = force === undefined ? !isFavorited : force;
+	if (shouldAdd === isFavorited) return;
+	if (shouldAdd) {
+		await state.api.star(song.id);
+		state.favorites.add(song.id);
+	} else {
+		await state.api.unstar(song.id);
+		state.favorites.delete(song.id);
+	}
+};
+
+// highlight currently playing song in queue
+function highlightCurrentTrack() {
+	clearRowClasses(ui.queueList, "tr", ["currently-playing"]);
+	if (state.queueIndex >= 0) {
+		const row = ui.queueList.querySelector(
+			`tr[data-index="${state.queueIndex}"]`,
+		);
+		if (row) row.classList.add("currently-playing");
+	}
+}
+
+// move to next track when current song ends
+function handleTrackEnd() {
+	if (
+		isValidQueueIndex(state.queueIndex, state.queue.length) &&
+		state.settings.scrobbling
+	) {
+		state.api?.scrobble(state.queue[state.queueIndex].id).catch(() => {});
+	}
+	state.queueIndex++;
+	if (state.queueIndex < state.queue.length) {
+		saveQueue();
+		playTrack(state.queue[state.queueIndex]);
+	} else {
+		ui.player.src = "";
+		ui.trackTitle.textContent = MESSAGES.PLAYBACK_FINISHED;
+	}
+}
+
+// reset player when stopping or clearing queue
+function resetPlayerUI() {
+	ui.player.pause();
+	ui.player.src = "";
+	ui.trackTitle.textContent = MESSAGES.NO_TRACK_PLAYING;
+	ui.trackArtist.textContent = "";
+	clearLyrics();
+	ui.coverArt.src = "static/subsonic.png";
+	ui.progress.value = 0;
+	ui.timeDisplay.textContent = "0:00 / 0:00";
+	updatePlayIcon();
+	withMediaSession((ms) => (ms.metadata = null));
+}
+
+// safely call mediaSession methods if available
+const withMediaSession = (callback) => {
+	if (navigator.mediaSession) callback(navigator.mediaSession);
+};
+
+// update media session metadata with current song
+const updateMediaSession = (song) => {
+	if (!song) return;
+	withMediaSession((ms) => {
+		ms.metadata = new MediaMetadata({
+			title: song.title || "Unknown",
+			artist: song.artist || "Unknown Artist",
+			album: song.album || "",
+			artwork: song.coverArt
+				? [
+						{
+							src: state.api.getCoverArtUrl(song.coverArt, 256),
+							sizes: "512x512",
+							type: "image/jpeg",
+						},
+					]
+				: [],
+		});
+		updateMediaSessionPosition();
+	});
+};
+
+let lastMediaSessionUpdateTime = 0;
+// throttled update of playback position for media session
+const updateMediaSessionPosition = () => {
+	const now = Date.now();
+	if (now - lastMediaSessionUpdateTime < 200) {
+		return;
+	}
+	lastMediaSessionUpdateTime = now;
+	withMediaSession((ms) => {
+		ms.setPositionState({
+			duration: ui.player.duration || 0,
+			playbackRate: 1,
+			position: ui.player.currentTime || 0,
+		});
+	});
+};

src/js/queue.js

···
+// some of this was taken from various sources on stackoverflow and some of it was also ai-assisted, it's likely rough around the edges in places and could use improvements
+// too complex for my brain 🐈
+
+// persist queue and current index to localStorage
+function saveQueue() {
+	try {
+		const serialized = state.queue.map((song) => ({
+			id: song.id,
+			title: song.title,
+			artist: song.artist,
+			album: song.album,
+			coverArt: song.coverArt,
+			duration: song.duration,
+		}));
+		localStorage.setItem("tinysub_queue", JSON.stringify(serialized));
+		localStorage.setItem(
+			"tinysub_queue_index",
+			JSON.stringify(state.queueIndex),
+		);
+	} catch (e) {
+		// quota exceeded, just save current track index
+		if (e.name === "QuotaExceededError") {
+			try {
+				localStorage.setItem(
+					"tinysub_queue_index",
+					JSON.stringify(state.queueIndex),
+				);
+			} catch {
+				// even index won't fit, give up silently
+			}
+		}
+	}
+}
+
+// update queue display, highlight current track, and save state
+function updateQueue(updateDisplay = true) {
+	if (updateDisplay) updateQueueDisplay();
+	saveQueue();
+}
+
+// restore queue from localStorage
+function loadQueue() {
+	const saved = localStorage.getItem("tinysub_queue");
+	if (!saved) return false;
+
+	try {
+		state.queue = JSON.parse(saved);
+		const savedIndex = localStorage.getItem("tinysub_queue_index");
+		if (savedIndex !== null) {
+			const index = JSON.parse(savedIndex);
+			if (isValidQueueIndex(index, state.queue.length)) {
+				state.queueIndex = index;
+			}
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const SONG_EXTRACTORS = {
+	artist: async (data) => {
+		const albums = data.artist?.album || [];
+		const songArrays = await Promise.all(
+			albums.map((album) =>
+				state.api
+					.getAlbum(album.id)
+					.then((result) => result.album?.song || [])
+					.catch(() => []),
+			),
+		);
+		return songArrays.flat();
+	},
+	album: (data) => data.album?.song || [],
+	playlist: (data) => data.entry || data.playlist?.entry || [],
+	song: (s) => [s],
+};
+
+// add songs to queue (with optional insertNext mode)
+async function addToQueue(fetcher, songExtractor, insertNext = false) {
+	const songs = await songExtractor(await fetcher());
+	if (insertNext) {
+		const insertPos = state.queueIndex >= 0 ? state.queueIndex + 1 : 0;
+		state.queue.splice(insertPos, 0, ...songs);
+	} else {
+		state.queue.push(...songs);
+	}
+	updateQueue();
+}
+
+const addArtistToQueue = (id) =>
+	addToQueue(() => state.api.getArtist(id), SONG_EXTRACTORS.artist);
+const addAlbumToQueue = (id) =>
+	addToQueue(() => state.api.getAlbum(id), SONG_EXTRACTORS.album);
+const addPlaylistToQueue = (id) =>
+	addToQueue(() => state.api.getPlaylist(id), SONG_EXTRACTORS.playlist);
+const addSongToQueue = (song) =>
+	addToQueue(() => Promise.resolve(song), SONG_EXTRACTORS.song);
+
+// virtual scrolling state with dynamic row height measurement
+const VIRTUAL_SCROLL = {
+	rowHeight: null,
+	buffer: 4,
+	container: null,
+	visibleStart: 0,
+	visibleEnd: 0,
+	initialized: false,
+	measured: false,
+	rowCache: new Map(),
+	scrollScheduled: false,
+};
+
+// setup scroll and resize listeners
+function initVirtualScroll() {
+	if (VIRTUAL_SCROLL.initialized) return;
+	VIRTUAL_SCROLL.initialized = true;
+
+	VIRTUAL_SCROLL.container = document.querySelector("main");
+	if (!VIRTUAL_SCROLL.container) return;
+
+	VIRTUAL_SCROLL.container.addEventListener("scroll", handleVirtualScroll, {
+		passive: true,
+	});
+	window.addEventListener("resize", () => {
+		VIRTUAL_SCROLL.rowHeight = null;
+		VIRTUAL_SCROLL.measured = false;
+		VIRTUAL_SCROLL.rowCache.clear();
+		handleVirtualScroll(true);
+	});
+}
+
+// calculate which rows are visible given current scroll position
+function calculateVisibleRange(scrollTop, viewportHeight) {
+	if (!VIRTUAL_SCROLL.rowHeight) {
+		return { start: 0, end: state.queue.length };
+	}
+	return {
+		start: Math.max(
+			0,
+			Math.floor(scrollTop / VIRTUAL_SCROLL.rowHeight) - VIRTUAL_SCROLL.buffer,
+		),
+		end: Math.min(
+			state.queue.length,
+			Math.ceil((scrollTop + viewportHeight) / VIRTUAL_SCROLL.rowHeight) +
+				VIRTUAL_SCROLL.buffer,
+		),
+	};
+}
+
+// update visible rows on scroll (throttled with requestAnimationFrame)
+function handleVirtualScroll(forceRender = false) {
+	if (!VIRTUAL_SCROLL.container) return;
+
+	if (VIRTUAL_SCROLL.scrollScheduled && !forceRender) return;
+	VIRTUAL_SCROLL.scrollScheduled = true;
+
+	requestAnimationFrame(() => {
+		const range = calculateVisibleRange(
+			VIRTUAL_SCROLL.container.scrollTop,
+			VIRTUAL_SCROLL.container.clientHeight,
+		);
+
+		if (
+			forceRender ||
+			range.start !== VIRTUAL_SCROLL.visibleStart ||
+			range.end !== VIRTUAL_SCROLL.visibleEnd
+		) {
+			VIRTUAL_SCROLL.visibleStart = range.start;
+			VIRTUAL_SCROLL.visibleEnd = range.end;
+			renderVirtualRows(forceRender);
+			highlightCurrentTrack();
+		}
+		VIRTUAL_SCROLL.scrollScheduled = false;
+	});
+}
+
+// render visible rows and spacers, measure actual row height
+function renderVirtualRows(forceRender = true) {
+	const { visibleStart, visibleEnd } = VIRTUAL_SCROLL;
+
+	for (const [idx, row] of VIRTUAL_SCROLL.rowCache.entries()) {
+		if (idx < visibleStart || idx >= visibleEnd) {
+			row.remove();
+			VIRTUAL_SCROLL.rowCache.delete(idx);
+		}
+	}
+
+	const newContent = [];
+
+	// create spacer row (invisible, used for scroll height)
+	const createSpacer = (rowCount) => {
+		const spacer = document.createElement("tr");
+		spacer.style.height = `${rowCount * VIRTUAL_SCROLL.rowHeight}px`;
+		spacer.classList.add("virtual-spacer");
+		return spacer;
+	};
+
+	if (visibleStart > 0) newContent.push(createSpacer(visibleStart));
+
+	for (let idx = visibleStart; idx < visibleEnd; idx++) {
+		let row = VIRTUAL_SCROLL.rowCache.get(idx);
+		if (!row) {
+			row = createQueueRow(state.queue[idx], idx);
+			VIRTUAL_SCROLL.rowCache.set(idx, row);
+		}
+		newContent.push(row);
+	}
+
+	const remainingRows = state.queue.length - visibleEnd;
+	if (remainingRows > 0) newContent.push(createSpacer(remainingRows));
+
+	ui.queueList.replaceChildren(...newContent);
+	updateSelectionUI();
+
+	if (forceRender && !VIRTUAL_SCROLL.measured && visibleStart < visibleEnd) {
+		requestAnimationFrame(() => {
+			const firstRow = ui.queueList.querySelector("tr:not(.virtual-spacer)");
+			if (firstRow?.offsetHeight > 0) {
+				const measured = firstRow.offsetHeight;
+				if (measured !== VIRTUAL_SCROLL.rowHeight) {
+					VIRTUAL_SCROLL.rowHeight = measured;
+					const newRange = calculateVisibleRange(
+						VIRTUAL_SCROLL.container.scrollTop,
+						VIRTUAL_SCROLL.container.clientHeight,
+					);
+					if (
+						newRange.start !== VIRTUAL_SCROLL.visibleStart ||
+						newRange.end !== VIRTUAL_SCROLL.visibleEnd
+					) {
+						VIRTUAL_SCROLL.visibleStart = newRange.start;
+						VIRTUAL_SCROLL.visibleEnd = newRange.end;
+						renderVirtualRows(false);
+						highlightCurrentTrack();
+					}
+				}
+			}
+			VIRTUAL_SCROLL.measured = true;
+		});
+	}
+}
+
+// clear cache and reset height measurement when queue changes
+function updateQueueDisplay() {
+	ui.queueCount.textContent = state.queue.length;
+	VIRTUAL_SCROLL.rowCache.clear();
+	VIRTUAL_SCROLL.rowHeight = null;
+	VIRTUAL_SCROLL.measured = false;
+	initVirtualScroll();
+	handleVirtualScroll(true);
+}
+
+// remove all selected rows with smart index adjustment
+function removeSelectedRows() {
+	const toRemove = getSelectedIndices();
+	if (toRemove.length === 0) return;
+
+	const toRemoveSet = new Set(toRemove);
+	const wasCurrentTrackDeleted = toRemoveSet.has(state.queueIndex);
+
+	state.queue = state.queue.filter((_, idx) => !toRemoveSet.has(idx));
+
+	if (!wasCurrentTrackDeleted && state.queueIndex >= 0) {
+		// adjust index for deleted rows before current track
+		state.queueIndex -= toRemove.filter((i) => i < state.queueIndex).length;
+	} else if (wasCurrentTrackDeleted) {
+		// find safe replacement if current track was deleted
+		state.queueIndex = Math.min(state.queueIndex, state.queue.length - 1);
+		if (state.queueIndex >= 0) {
+			playTrack(state.queue[state.queueIndex]);
+		} else {
+			resetPlayerUI();
+		}
+	}
+
+	clearSelection();
+	updateQueue();
+	// ensure highlight applies with correct adjusted index
+	highlightCurrentTrack();
+}
+
+// randomly reorder queue items while preserving current track position
+function shuffleQueue() {
+	const currentTrack =
+		state.queueIndex >= 0 ? state.queue[state.queueIndex] : null;
+
+	for (let i = state.queue.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[state.queue[i], state.queue[j]] = [state.queue[j], state.queue[i]];
+	}
+
+	if (currentTrack) {
+		state.queueIndex = state.queue.indexOf(currentTrack);
+	}
+
+	updateQueueDisplay();
+}
+
+// remove all items from queue
+function clearQueue() {
+	state.queue = [];
+	state.queueIndex = -1;
+	saveQueue();
+	resetPlayerUI();
+	updateQueueDisplay();
+}
+
+// button config for queue row actions, cached to avoid repeated creation
+const ROW_BUTTON_CONFIG = [
+	{
+		className: CLASSES.QUEUE_ACTION,
+		label: "play",
+		icon: ICONS.PLAY,
+	},
+	{
+		className: CLASSES.QUEUE_PLAY_NEXT,
+		label: "play next",
+		icon: ICONS.PLAY_NEXT,
+	},
+	{
+		className: CLASSES.QUEUE_FAVORITE,
+		label: "favorite",
+		icon: ICONS.FAVORITE,
+	},
+	{
+		className: CLASSES.QUEUE_MOVE_UP,
+		label: "move up",
+		icon: ICONS.MOVE_UP,
+	},
+	{
+		className: CLASSES.QUEUE_MOVE_DOWN,
+		label: "move down",
+		icon: ICONS.MOVE_DOWN,
+	},
+	{
+		className: CLASSES.QUEUE_REMOVE,
+		label: "remove",
+		icon: ICONS.REMOVE,
+	},
+];
+
+// create table row element for a song in queue
+function createQueueRow(song, idx) {
+	const tr = document.createElement("tr");
+	tr.draggable = true;
+	tr.setAttribute(DATA_ATTRS.INDEX, idx);
+	tr.classList.toggle("stripe", idx % 2 === 1);
+
+	// helper to create and append text cell
+	const createTextCell = (content) => {
+		const cell = document.createElement("td");
+		cell.textContent = content;
+		tr.appendChild(cell);
+	};
+
+	// cover art cell
+	const coverCell = document.createElement("td");
+	const songArtId = shouldShowArt("artSong", song.coverArt);
+	if (songArtId) {
+		const img = document.createElement("img");
+		img.src = state.api.getCoverArtUrl(songArtId, getArtFetchSize("artSong"));
+		img.alt = "cover";
+		img.className = CLASSES.QUEUE_COVER;
+		coverCell.appendChild(img);
+	}
+	tr.appendChild(coverCell);
+
+	// text cells
+	createTextCell(song.title);
+	createTextCell(song.artist || "");
+	createTextCell(song.album || "");
+	createTextCell(formatDuration(song.duration));
+
+	// action buttons cell
+	const actionsCell = document.createElement("td");
+	const btnFragment = document.createDocumentFragment();
+
+	ROW_BUTTON_CONFIG.forEach(({ className, label, icon }) => {
+		const btn = createIconButton(className, label, icon, label);
+		if (className === CLASSES.QUEUE_FAVORITE && state.favorites.has(song.id)) {
+			btn.classList.add(CLASSES.FAVORITED);
+		}
+		btnFragment.appendChild(btn);
+	});
+
+	actionsCell.appendChild(btnFragment);
+	tr.appendChild(actionsCell);
+
+	return tr;
+}

src/js/selection-manager.js

···
+// manages row selection state for queue table (single, multi, range)
+class SelectionManager {
+	constructor(container, options = {}) {
+		this.container = container;
+		this.selected = new Set();
+		this.lastSelected = null;
+		this.rowSelector = options.rowSelector || "tr";
+		this.indexAttribute = options.indexAttribute || "data-index";
+		this.selectedClass = options.selectedClass || "selected";
+		this.listeners = [];
+	}
+
+	getRowIndex(row) {
+		// get index from row element
+		return parseInt(row.getAttribute(this.indexAttribute));
+	}
+
+	select(index, options = {}) {
+		const { multi = false, shift = false } = options;
+
+		if (shift && this.lastSelected !== null) {
+			// range selection from last selected
+			const start = Math.min(this.lastSelected, index);
+			const end = Math.max(this.lastSelected, index);
+			for (let i = start; i <= end; i++) {
+				this.selected.add(i);
+			}
+		} else if (multi) {
+			// toggle selection with ctrl/cmd
+			this.selected.has(index)
+				? this.selected.delete(index)
+				: this.selected.add(index);
+		} else {
+			// single selection, clear others
+			this.selected.clear();
+			this.selected.add(index);
+		}
+
+		this.lastSelected = index;
+		this.updateUI();
+		this.notifyListeners();
+	}
+
+	clear() {
+		// clear selection
+		this.selected.clear();
+		this.lastSelected = null;
+		this.updateUI();
+		this.notifyListeners();
+	}
+
+	isSelected(index) {
+		// check if index is in selection
+		return this.selected.has(index);
+	}
+
+	getSelected() {
+		// return all selected indices sorted
+		return Array.from(this.selected).sort((a, b) => a - b);
+	}
+
+	count() {
+		// get number of selected items
+		return this.selected.size;
+	}
+
+	updateUI() {
+		// update dom to match selection state, only change what's different
+		const rows = this.container.querySelectorAll(this.rowSelector);
+		rows.forEach((row) => {
+			const idx = this.getRowIndex(row);
+			const isSelected = this.selected.has(idx);
+			const hasClass = row.classList.contains(this.selectedClass);
+
+			// only update dom if state changed
+			if (isSelected !== hasClass) {
+				isSelected
+					? row.classList.add(this.selectedClass)
+					: row.classList.remove(this.selectedClass);
+			}
+		});
+	}
+
+	onChange(callback) {
+		// register listener for selection changes
+		this.listeners.push(callback);
+	}
+
+	notifyListeners() {
+		// notify all listeners of selection changes
+		this.listeners.forEach((callback) => {
+			callback(this.getSelected());
+		});
+	}
+
+	setSelection(indices) {
+		// set selection from external source (for programmatic updates)
+		this.selected.clear();
+		indices.forEach((idx) => this.selected.add(idx));
+		this.lastSelected = indices.length > 0 ? indices[indices.length - 1] : null;
+		this.updateUI();
+		this.notifyListeners();
+	}
+}
+
+// wrapper functions for legacy compatibility and convenience
+function selectRow(index, multiSelect = false, shiftSelect = false) {
+	selectionManager.select(index, { multi: multiSelect, shift: shiftSelect });
+}
+
+function clearSelection() {
+	// clear all selected rows
+	selectionManager.clear();
+}
+
+function getSelectedIndices() {
+	// get all selected row indices
+	return selectionManager.getSelected();
+}
+
+// export selection manager methods through wrapper
+function updateSelectionUI() {
+	selectionManager.updateUI();
+}

src/js/settings.js

···
+// load settings from localStorage and apply to state
+function loadSettings() {
+	const saved = localStorage.getItem("tinysub_settings");
+	if (saved) {
+		try {
+			const loaded = JSON.parse(saved);
+			state.settings = { ...state.settings, ...loaded };
+		} catch {
+			// ignore parse errors, use defaults
+		}
+	}
+	applySettings();
+}
+
+// persist settings to localStorage
+function saveSettings() {
+	localStorage.setItem("tinysub_settings", JSON.stringify(state.settings));
+}
+
+// apply settings to CSS custom properties
+function applySettings() {
+	const mappings = { artist: "artArtist", album: "artAlbum", song: "artSong" };
+	Object.entries(mappings).forEach(([name, key]) => {
+		const size = state.settings[key];
+		document.documentElement.style.setProperty(
+			`--art-${name}`,
+			size === 0 ? "0px" : `${size}px`,
+		);
+	});
+}
+
+// return art id for rendering, or null if size is 0 (prevents DOM creation)
+function shouldShowArt(artType, artId) {
+	return state.settings[artType] > 0 ? artId : null;
+}
+
+// return fetch size for images at 2x the setting for retina displays
+function getArtFetchSize(artType) {
+	return Math.max(state.settings[artType] * 2, 32);
+}
+
+// setup settings modal and controls
+function setupSettings() {
+	const modal = document.getElementById("settings-modal");
+	const settingsBtn = document.getElementById("settings-btn");
+	const closeBtn = document.getElementById("close-settings-btn");
+	const scrobbleToggle = document.getElementById("scrobbling-toggle");
+
+	loadSettings();
+	scrobbleToggle.checked = state.settings.scrobbling;
+
+	const artTypes = [
+		{ name: "artist", key: "artArtist" },
+		{ name: "album", key: "artAlbum" },
+		{ name: "song", key: "artSong" },
+	];
+
+	const sliderConfig = artTypes.map(({ name, key }) => ({
+		input: document.getElementById(`${name}-size`),
+		display: document.getElementById(`${name}-size-display`),
+		key,
+	}));
+
+	sliderConfig.forEach(({ input, display, key }) => {
+		input.value = state.settings[key];
+		display.textContent = input.value;
+	});
+
+	const toggleModal = (show) => modal.classList.toggle("hidden", !show);
+	settingsBtn.addEventListener("click", () => toggleModal(true));
+	closeBtn.addEventListener("click", () => toggleModal(false));
+	modal.addEventListener("click", (e) => {
+		if (e.target === modal) toggleModal(false);
+	});
+
+	scrobbleToggle.addEventListener("change", () => {
+		state.settings.scrobbling = scrobbleToggle.checked;
+		saveSettings();
+	});
+
+	sliderConfig.forEach(({ input, display, key }) => {
+		input.addEventListener("input", () => {
+			display.textContent = input.value;
+		});
+
+		input.addEventListener("change", () => {
+			state.settings[key] = parseInt(input.value);
+			applySettings();
+			saveSettings();
+			triggerQueueRefresh();
+		});
+	});
+}
+
+// trigger refresh of queue and library when art sizes change
+function triggerQueueRefresh() {
+	VIRTUAL_SCROLL.rowHeight = null;
+	VIRTUAL_SCROLL.measured = false;
+	VIRTUAL_SCROLL.rowCache.clear();
+	handleVirtualScroll(true);
+	renderLibraryTree();
+	renderPlaylistsTree();
+}

src/js/state.js

···
+// app state with api, library, queue, and user preferences
+const state = {
+	api: null,
+	library: [],
+	playlists: [],
+	queue: [],
+	queueIndex: -1,
+	favorites: new Set(),
+	expanded: {
+		artists: false,
+		playlists: false,
+		items: {
+			artists: {},
+			albums: {},
+		},
+	},
+	settings: {
+		scrobbling: true,
+		artArtist: 0,
+		artAlbum: 32,
+		artSong: 16,
+	},
+};
+
+// dom element references cached for quick access
+const ui = {
+	loginForm: document.getElementById(DOM_IDS.LOGIN_FORM),
+	serverInput: document.getElementById(DOM_IDS.SERVER_INPUT),
+	usernameInput: document.getElementById(DOM_IDS.USERNAME_INPUT),
+	passwordInput: document.getElementById(DOM_IDS.PASSWORD_INPUT),
+	authError: document.getElementById(DOM_IDS.AUTH_ERROR),
+	artistsTree: document.getElementById(DOM_IDS.LIBRARY_TREE),
+	playlistsTree: document.getElementById(DOM_IDS.PLAYLISTS_TREE),
+	queueList: document.getElementById(DOM_IDS.QUEUE_LIST),
+	queueCount: document.getElementById(DOM_IDS.QUEUE_COUNT),
+	coverArt: document.getElementById(DOM_IDS.COVER_ART),
+	trackTitle: document.getElementById(DOM_IDS.TRACK_TITLE),
+	trackArtist: document.getElementById(DOM_IDS.TRACK_ARTIST),
+	trackLyric: document.getElementById(DOM_IDS.TRACK_LYRIC),
+	player: document.getElementById(DOM_IDS.PLAYER),
+	playBtn: document.getElementById(DOM_IDS.PLAY_BTN),
+	prevBtn: document.getElementById(DOM_IDS.PREV_BTN),
+	nextBtn: document.getElementById(DOM_IDS.NEXT_BTN),
+	progress: document.getElementById(DOM_IDS.PROGRESS),
+	timeDisplay: document.getElementById(DOM_IDS.TIME_DISPLAY),
+	logoutBtn: document.getElementById(DOM_IDS.LOGOUT_BTN),
+	settingsBtn: document.getElementById("settings-btn"),
+	sectionToggles: document.querySelectorAll(`.${DOM_IDS.SECTION_TOGGLE}`),
+	shuffleBtn: document.getElementById(DOM_IDS.SHUFFLE_BTN),
+	clearBtn: document.getElementById(DOM_IDS.CLEAR_BTN),
+};

src/js/ui.js

···
+// update play button icon based on playback state
+const updatePlayIcon = () => {
+	const iconPath = ui.player.paused ? ICONS.PLAY : ICONS.PAUSE;
+	const label = ui.player.paused ? "play" : "pause";
+	ui.playBtn.innerHTML = `<img src="${iconPath}" alt="${label}" />`;
+};
+
+// create tree item with cover art and action buttons
+function createTreeItem(
+	name,
+	coverArtId,
+	onToggle,
+	onAdd,
+	onPlayNext,
+	artType,
+	itemId,
+) {
+	const li = createElement("li");
+	const div = createElement("div", { className: CLASSES.TREE_ITEM });
+
+	if (itemId) li.dataset.itemId = itemId;
+
+	const linkChildren = [];
+	if (coverArtId) {
+		linkChildren.push(
+			createElement("img", {
+				attributes: {
+					src: state.api.getCoverArtUrl(coverArtId, getArtFetchSize(artType)),
+					alt: "cover",
+					loading: "lazy",
+				},
+			}),
+		);
+	}
+	linkChildren.push(createElement("span", { textContent: name }));
+
+	const linkEl = createElement("a", {
+		className: onToggle ? CLASSES.TREE_TOGGLE : CLASSES.TREE_NAME,
+		attributes: { href: "#" },
+		listeners: {
+			click: (e) => {
+				e.preventDefault();
+				onToggle ? onToggle(li) : onAdd?.();
+			},
+		},
+		children: linkChildren,
+	});
+
+	div.appendChild(linkEl);
+	if (onPlayNext)
+		div.appendChild(
+			createIconButton(
+				"tree-action",
+				"play next",
+				ICONS.PLAY_NEXT,
+				"play next",
+				onPlayNext,
+			),
+		);
+	if (onAdd)
+		div.appendChild(
+			createIconButton("tree-action", "add", ICONS.ADD, "add", onAdd),
+		);
+
+	li.appendChild(div);
+	return li;
+}
+
+const SECTION_RENDERERS = {
+	artists: renderLibraryTree,
+	playlists: renderPlaylistsTree,
+};
+
+// toggle library section expand/collapse
+function handleSectionToggle(e) {
+	e.preventDefault();
+	const section = e.target.dataset.section;
+	state.expanded[section] = !state.expanded[section];
+	if (
+		state.expanded[section] &&
+		typeof state.expanded.items[section] === "undefined"
+	) {
+		state.expanded.items[section] = {};
+	}
+	SECTION_RENDERERS[section]?.();
+}
+
+// toggle auth modal
+const toggleAuthModal = (show) => {
+	document.getElementById(DOM_IDS.AUTH_MODAL).classList.toggle("hidden", !show);
+};

src/js/utils.js

···
+// format seconds as mm:ss string
+function formatDuration(seconds) {
+	if (!seconds || !Number.isFinite(seconds)) return "0:00";
+	const minutes = Math.floor(seconds / 60);
+	return `${minutes}:${Math.floor(seconds % 60)
+		.toString()
+		.padStart(2, "0")}`;
+}
+
+// get row index from data attribute
+function getRowIndex(rowEl, attrName = "data-index") {
+	return parseInt(rowEl.getAttribute(attrName));
+}
+
+// find closest row element
+function getClosestRow(el, rowSelector = "tr") {
+	return el.closest(rowSelector);
+}
+
+// generic element creator
+function createElement(tag, config = {}) {
+	const {
+		className,
+		textContent,
+		html,
+		attributes = {},
+		listeners = {},
+		children = [],
+	} = config;
+	const el = document.createElement(tag);
+	if (className) el.className = className;
+	if (textContent) el.textContent = textContent;
+	if (html) el.innerHTML = html;
+	Object.entries(attributes).forEach(([key, value]) =>
+		el.setAttribute(key, value),
+	);
+	Object.entries(listeners).forEach(([event, handler]) =>
+		el.addEventListener(event, handler),
+	);
+	children.forEach((child) => el.appendChild(child));
+	return el;
+}
+
+// create a button with icon
+function createIconButton(className, ariaLabel, iconPath, iconAlt, onCallback) {
+	const btn = createElement("button", {
+		className,
+		attributes: { "aria-label": ariaLabel },
+		children: [
+			createElement("img", { attributes: { src: iconPath, alt: iconAlt } }),
+		],
+	});
+
+	if (onCallback) {
+		btn.addEventListener("click", async (e) => {
+			e.preventDefault();
+			btn.classList.add(CLASSES.DISABLED);
+			try {
+				await onCallback();
+			} finally {
+				btn.classList.remove(CLASSES.DISABLED);
+			}
+		});
+	}
+
+	return btn;
+}
+
+// remove classes from only elements that have them
+function clearRowClasses(container, rowSelector, classNames) {
+	const classes = Array.isArray(classNames) ? classNames : [classNames];
+	container.querySelectorAll(rowSelector).forEach((row) => {
+		classes.forEach((cls) => row.classList.remove(cls));
+	});
+}
+
+// add or remove class from specific rows
+function updateRowClass(container, indices, className, add = true) {
+	const indexSet = new Set(indices);
+	container.querySelectorAll("tr").forEach((row) => {
+		const idx = getRowIndex(row);
+		row.classList.toggle(className, indexSet.has(idx) === add);
+	});
+}
+
+function isValidQueueIndex(index, queueLength) {
+	return index >= 0 && index < queueLength;
+}
+
+// move items within queue and maintain proper indices
+function moveQueueItems(queue, selectedIndices, insertPos, callbacks = {}) {
+	const { onSelectionChange, onQueueChange } = callbacks;
+	const sortedIndices = Array.from(selectedIndices).sort((a, b) => a - b);
+	const movedItems = sortedIndices.map((i) => queue[i]);
+
+	// remove items in reverse order to avoid index shifting
+	for (
+		let i = sortedIndices[sortedIndices.length - 1];
+		i >= sortedIndices[0];
+		i--
+	) {
+		if (selectedIndices.includes(i)) queue.splice(i, 1);
+	}
+
+	// normalize insert position for removed items
+	insertPos -= sortedIndices.filter((i) => i < insertPos).length;
+
+	// insert moved items at target position
+	queue.splice(insertPos, 0, ...movedItems);
+
+	// update queue index for moved/removed items
+	if (state.queueIndex >= 0) {
+		if (selectedIndices.includes(state.queueIndex)) {
+			const positionInMoved = sortedIndices.filter(
+				(i) => i < state.queueIndex,
+			).length;
+			state.queueIndex = insertPos + positionInMoved;
+		} else {
+			const newIndex =
+				state.queueIndex -
+				sortedIndices.filter((i) => i < state.queueIndex).length;
+			state.queueIndex =
+				insertPos <= newIndex ? newIndex + movedItems.length : newIndex;
+		}
+	}
+
+	saveQueue();
+
+	// batch DOM updates together to avoid reflows
+	if (onSelectionChange)
+		onSelectionChange(sortedIndices.map((_, i) => insertPos + i));
+	if (onQueueChange) onQueueChange();
+}

src/js/validation.js

···
+// build validation response object
+const buildValidation = (valid, value, error) => ({
+	valid,
+	...(valid ? { value } : { error }),
+});
+
+// check if id is present and valid type
+function validateId(value, fieldName = "ID") {
+	const isValid =
+		value && (typeof value === "string" || typeof value === "number");
+	return buildValidation(isValid, value, `${fieldName} is required`);
+}
+
+// validate server URL is valid HTTP(S) format
+function validateServerUrl(url) {
+	if (!url || typeof url !== "string") {
+		return buildValidation(false, null, "Server URL is required");
+	}
+
+	const trimmed = url.trim();
+	if (!trimmed) {
+		return buildValidation(false, null, "Server URL cannot be empty");
+	}
+
+	try {
+		const urlObj = new URL(trimmed);
+		const isValid = ["http:", "https:"].includes(urlObj.protocol);
+		return buildValidation(
+			isValid,
+			trimmed,
+			isValid ? null : "Server URL must use HTTP or HTTPS",
+		);
+	} catch {
+		return buildValidation(false, null, "Invalid URL format");
+	}
+}
+
+// validate username and password meet requirements
+function validateCredentials(username, password) {
+	const errors = [];
+
+	if (!username || typeof username !== "string" || !username.trim()) {
+		errors.push("Username is required");
+	} else if (username.length > 255) {
+		errors.push("Username is too long (max 255 characters)");
+	}
+
+	if (!password || typeof password !== "string" || !password) {
+		errors.push("Password is required");
+	} else if (password.length > 1000) {
+		errors.push("Password is too long");
+	}
+
+	if (errors.length > 0) {
+		return buildValidation(false, null, errors.join("; "));
+	}
+
+	return buildValidation(true, { username: username.trim(), password });
+}