refactor: rewrite virtual scroller

i stuck with spacers because vue-virtual-scroll's method of using minheight didnt really work well for tables. but this is less buggy and far cleaner

src/css/components.css

···
 	margin-top: 0.5rem;
 }
 
-/* hint optimization for virtual scroll updates */
-tbody {
-	will-change: contents;
-}
-
 th,
 td {
 	text-align: left;

src/css/layout.css

···
 	grid-area: main;
 	overflow-y: auto;
 	padding-inline: 1rem;
-	-webkit-overflow-scrolling: touch;
 }
 
 /* action buttons and version info */

src/index.html

···
 		<script src="js/state.js"></script>
 		<script src="js/settings.js"></script>
 		<script src="js/image-cache.js"></script>
+		<script src="js/virtual-scroll.js"></script>
 		<script src="js/queue.js"></script>
 		<script src="js/library.js"></script>
 		<script src="js/ui.js"></script>

src/js/draggable.js

···
 // setup drag and drop for queue reordering
 function setupDragAndDrop() {
 	const clearDragOver = () =>
-		clearRowClasses(ui.queueList, "tr:not(.virtual-spacer)", [
+		clearRowClasses(ui.queueList, "tr", [
 			CLASSES.DRAG_OVER_ABOVE,
 			CLASSES.DRAG_OVER_BELOW,
 			CLASSES.DRAGGING,
 		]);
 	const isDraggable = (row) =>
 		row &&
-		!row.classList.contains(CLASSES.DRAGGING) &&
-		!row.classList.contains("virtual-spacer");
+		!row.classList.contains(CLASSES.DRAGGING);
 	const isDropBelowCenter = (e, row) =>
 		e.clientY - row.getBoundingClientRect().top > row.offsetHeight / 2;
 
···
 		const row = getClosestRow(e.target);
 		if (!isDraggable(row)) return;
 
-		clearRowClasses(ui.queueList, "tr:not(.virtual-spacer)", [
+		clearRowClasses(ui.queueList, "tr", [
 			CLASSES.DRAG_OVER_ABOVE,
 			CLASSES.DRAG_OVER_BELOW,
 		]);

src/js/events.js

···
 		selectedClass: CLASSES.SELECTED,
 	});
 
-	// initialize virtual scrolling for queue
-	initVirtualScroll();
-
 	// setup settings modal
 	setupSettings();
 
···
 	// setup event handlers
 	setupDragAndDrop();
 	setupQueueContextMenu();
+	initVirtualScroller();
 	setupKeyboardShortcuts();
 	setupMediaSessionHandlers();
 

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 {
···
 			}
 		}
 	}
-}
-
-// update queue display and save state
-function updateQueue() {
-	updateQueueDisplay();
-	saveQueue();
 }
 
 // restore queue from localStorage
···
 const addSongToQueue = (song) =>
 	addToQueue(() => Promise.resolve(song), SONG_EXTRACTORS.song);
 
-// virtual scrolling state with dynamic row height measurement
-const VIRTUAL_SCROLL = {
-	rowHeight: null,
-	buffer: 16,
-	container: null,
-	visibleStart: 0,
-	visibleEnd: 0,
-	wrapper: null,
-	scrollScheduled: false,
-	measurementScheduled: false,
-	SPACER_CLASS: "virtual-spacer",
-};
-
-function resetVirtualScrollMeasurements() {
-	VIRTUAL_SCROLL.rowHeight = null;
+// update queue display and save state
+function updateQueue() {
+	updateQueueDisplay();
+	saveQueue();
 }
 
-// setup scroll and resize listeners
-function initVirtualScroll() {
-	if (VIRTUAL_SCROLL.container) return;
-
-	VIRTUAL_SCROLL.container = document.querySelector("main");
-	if (!VIRTUAL_SCROLL.container) return;
-
-	VIRTUAL_SCROLL.wrapper = ui.queueList;
-
-	VIRTUAL_SCROLL.container.addEventListener("scroll", handleVirtualScroll, {
-		passive: true,
-	});
-	window.addEventListener("resize", () => {
-		handleVirtualScroll(false);
-	});
-}
-
-// calculate which rows are visible given current scroll position
-function calculateVisibleRange(scrollTop, viewportHeight) {
-	if (!VIRTUAL_SCROLL.rowHeight) {
-		return { start: 0, end: state.queue.length };
-	}
-
-	const rowHeight = VIRTUAL_SCROLL.rowHeight;
-	return {
-		start: Math.max(
-			0,
-			Math.floor(scrollTop / rowHeight) - VIRTUAL_SCROLL.buffer,
-		),
-		end: Math.min(
-			state.queue.length,
-			Math.ceil((scrollTop + viewportHeight) / rowHeight) +
-				VIRTUAL_SCROLL.buffer,
-		),
-	};
-}
-
-// update visible rows on scroll
-function handleVirtualScroll(forceRender = false) {
-	if (!VIRTUAL_SCROLL.container) return;
-
-	if (VIRTUAL_SCROLL.scrollScheduled && !forceRender) return;
-	VIRTUAL_SCROLL.scrollScheduled = true;
+let virtualScroller = null;
 
-	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();
+// initialize virtual scroller for queue table
+function initVirtualScroller() {
+	if (virtualScroller) return;
+	const container = document.querySelector('main');
+	if (!container) return;
+	
+	virtualScroller = new VirtualScroller(
+		container,
+		ui.queueList,
+		state.queue.length,
+		(idx) => createQueueRow(state.queue[idx], idx),
+		{
+			onScroll: () => {
+				updateSelectionUI();
+				highlightCurrentTrack();
+			},
 		}
-		VIRTUAL_SCROLL.scrollScheduled = false;
-	});
-}
-
-// render visible rows with spacers
-function renderVirtualRows(forceRender = true) {
-	const { visibleStart, visibleEnd, wrapper } = VIRTUAL_SCROLL;
-	const rowHeight = VIRTUAL_SCROLL.rowHeight || 0;
-
-	// spacer rows for unrendered content
-	const topSpacer = document.createElement("tr");
-	topSpacer.style.height = `${visibleStart * rowHeight}px`;
-	topSpacer.classList.add(VIRTUAL_SCROLL.SPACER_CLASS);
-
-	const bottomSpacer = document.createElement("tr");
-	const remainingRows = state.queue.length - visibleEnd;
-	bottomSpacer.style.height = `${remainingRows * rowHeight}px`;
-	bottomSpacer.classList.add(VIRTUAL_SCROLL.SPACER_CLASS);
-
-	// collect rows to render
-	const newRows = [topSpacer];
-	for (let idx = visibleStart; idx < visibleEnd; idx++) {
-		newRows.push(createQueueRow(state.queue[idx], idx));
-	}
-	newRows.push(bottomSpacer);
-
-	wrapper.replaceChildren(...newRows);
-	updateSelectionUI();
-
-	// schedule measurement after structural changes
-	if (forceRender && !VIRTUAL_SCROLL.measurementScheduled) {
-		VIRTUAL_SCROLL.measurementScheduled = true;
-		requestAnimationFrame(() => {
-			if (visibleStart < visibleEnd) {
-				const firstRow = wrapper.querySelector(
-					`tr:not(.${VIRTUAL_SCROLL.SPACER_CLASS})`,
-				);
-				if (firstRow?.offsetHeight > 0) {
-					const measured = firstRow.offsetHeight;
-					if (VIRTUAL_SCROLL.rowHeight !== measured) {
-						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
-						) {
-							const oldRowCount =
-								VIRTUAL_SCROLL.visibleEnd - VIRTUAL_SCROLL.visibleStart;
-							const newRowCount = newRange.end - newRange.start;
-							const rowCountDiff = Math.abs(newRowCount - oldRowCount);
-							// only re-render if visible row count changed significantly (more than buffer)
-							if (rowCountDiff > VIRTUAL_SCROLL.buffer / 2) {
-								VIRTUAL_SCROLL.visibleStart = newRange.start;
-								VIRTUAL_SCROLL.visibleEnd = newRange.end;
-								renderVirtualRows(false);
-							}
-						}
-					}
-				}
-			}
-			VIRTUAL_SCROLL.measurementScheduled = false;
-			highlightCurrentTrack();
-		});
-	} else {
-		highlightCurrentTrack();
-	}
+	);
 }
 
-// update queue display and re-render with fresh visible range
+// update queue display using virtual scroller
 function updateQueueDisplay() {
 	ui.queueCount.textContent = state.queue.length;
-	handleVirtualScroll(true);
+	(virtualScroller || (initVirtualScroller(), virtualScroller))?.updateItemCount(state.queue.length);
 }
 
 // clear selected rows
···
 
 	const toRemoveSet = new Set(toRemove);
 	const wasCurrentTrackDeleted = toRemoveSet.has(state.queueIndex);
+	const deletionsBefore = toRemove.filter(idx => idx < state.queueIndex).length;
 
 	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;
+		state.queueIndex -= deletionsBefore;
 	} 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]);
···
 
 // randomly reorder queue items while preserving current track position
 function shuffleQueue() {
-	const currentTrack =
-		state.queueIndex >= 0 ? state.queue[state.queueIndex] : null;
+	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));
···
 	updateQueueDisplay();
 }
 
-// button config for queue row actions, cached to avoid repeated creation
+// buttons for queue row actions
 const ROW_BUTTON_CONFIG = [
 	{
 		className: CLASSES.QUEUE_ACTION,
···
 	},
 ];
 
-// set cover art cell content
-function setQueueCoverArt(cell, song) {
-	cell.replaceChildren();
-	const songArtId = shouldShowArt("artSong", song.coverArt);
-	const size = state.settings.artSong;
-
-	if (size > 0) {
-		// create wrapper to reserve space for image before it loads
-		const wrapper = document.createElement("div");
-		wrapper.style.width = `${size}px`;
-		wrapper.style.height = `${size}px`;
-		wrapper.style.flexShrink = "0";
-		wrapper.style.overflow = "hidden";
-
-		const img = document.createElement("img");
-		img.alt = "cover";
-		img.className = CLASSES.QUEUE_COVER;
-		img.style.width = "100%";
-		img.style.height = "100%";
-
-		wrapper.appendChild(img);
-		cell.appendChild(wrapper);
-
-		// load actual image if art should be shown
-		if (songArtId) {
-			loadCachedImage(img, songArtId, "artSong");
-		}
-	}
-}
-
 // 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);
-	tr.dataset.songId = song.id; // for event handling
+	tr.dataset.songId = song.id;
 
+	// batch all cells in fragment for efficient DOM insertion
+	const cells = document.createDocumentFragment();
+	
 	// cover art cell
 	const coverCell = document.createElement("td");
-	setQueueCoverArt(coverCell, song);
-	tr.appendChild(coverCell);
+	if (song.coverArt && state.settings.artSong > 0) {
+		const img = document.createElement("img");
+		img.className = "queue-cover";
+		coverCell.appendChild(img);
+		loadCachedImage(img, song.coverArt, "artSong");
+	}
+	cells.appendChild(coverCell);
 
 	// text cells
-	const createTextCell = (content) => {
-		const cell = document.createElement("td");
-		cell.textContent = content;
-		tr.appendChild(cell);
-	};
-	createTextCell(song.title);
-	createTextCell(song.artist || "");
-	createTextCell(song.album || "");
-	createTextCell(formatDuration(song.duration));
+	const titleCell = document.createElement("td");
+	titleCell.textContent = song.title;
+	cells.appendChild(titleCell);
+
+	const artistCell = document.createElement("td");
+	artistCell.textContent = song.artist || "";
+	cells.appendChild(artistCell);
+
+	const albumCell = document.createElement("td");
+	albumCell.textContent = song.album || "";
+	cells.appendChild(albumCell);
+
+	const durationCell = document.createElement("td");
+	durationCell.textContent = formatDuration(song.duration);
+	cells.appendChild(durationCell);
 
 	// action buttons cell
 	const actionsCell = document.createElement("td");
-	const btnFragment = document.createDocumentFragment();
-
+	const isFavorited = state.favorites.has(song.id);
 	ROW_BUTTON_CONFIG.forEach(({ className, label, icon }) => {
 		const btn = createIconButton(className, label, icon, label);
-		if (className === CLASSES.QUEUE_FAVORITE && state.favorites.has(song.id)) {
+		if (className === CLASSES.QUEUE_FAVORITE && isFavorited) {
 			btn.classList.add(CLASSES.FAVORITED);
 		}
-		btnFragment.appendChild(btn);
+		actionsCell.appendChild(btn);
 	});
-
-	actionsCell.appendChild(btnFragment);
-	tr.appendChild(actionsCell);
+	cells.appendChild(actionsCell);
 
+	tr.appendChild(cells);
 	return tr;
 }

src/js/settings.js

···
 
 // trigger refresh of queue and library when art sizes change
 function triggerQueueRefresh() {
-	resetVirtualScrollMeasurements();
-	handleVirtualScroll(true);
+	updateQueueDisplay();
 	renderLibraryTree();
 	renderPlaylistsTree();
 }

src/js/virtual-scroll.js

···
+const STRIPE_CLASS = 'stripe';
+
+class VirtualScroller {
+	// initialize virtual scroller with container, tbody, and row factory
+	constructor(container, tbody, itemCount, createRow, { buffer = 8, onScroll } = {}) {
+		Object.assign(this, { container, tbody, itemCount, createRow, buffer, onScroll });
+		this.visibleStart = this.visibleEnd = 0;
+		this.rafId = null;
+		this.resizeTimeout = null;
+		this.firstRender = true;
+		this.rowHeight = 0;
+		
+		this.handleScroll = () => this.scheduleRender();
+		this.handleResize = () => {
+			clearTimeout(this.resizeTimeout);
+			this.resizeTimeout = setTimeout(() => this.render(), 150);
+		};
+		
+		this.container.addEventListener('scroll', this.handleScroll, { passive: true });
+		window.addEventListener('resize', this.handleResize);
+		this.render();
+	}
+	
+	// batch scroll and resize events into a single render call via requestAnimationFrame
+	scheduleRender() {
+		if (this.rafId) return;
+		this.rafId = requestAnimationFrame(() => {
+			this.rafId = null;
+			this.render();
+		});
+	}
+	
+	// render visible rows with spacer rows for scroll height
+	render(forceRedraw = false) {
+		// measure row height on first render or when settings change
+		if (this.firstRender || forceRedraw) {
+			if (this.itemCount > 0) {
+				const sample = this.createRow(0);
+				this.tbody.appendChild(sample);
+				this.rowHeight = sample.offsetHeight;
+				sample.remove();
+			}
+			this.firstRender = false;
+		}
+		
+		if (!this.itemCount) {
+			this.tbody.replaceChildren();
+			return;
+		}
+		
+		// calculate visible range based on scroll position
+		const scrollTop = this.container.scrollTop;
+		const start = Math.max(0, Math.floor(scrollTop / this.rowHeight) - this.buffer);
+		const end = Math.min(
+			this.itemCount,
+			Math.ceil((scrollTop + this.container.clientHeight) / this.rowHeight) + this.buffer
+		);
+		
+		// skip render if visible range hasn't changed
+		if (!forceRedraw && start === this.visibleStart && end === this.visibleEnd) return;
+		
+		this.visibleStart = start;
+		this.visibleEnd = end;
+		
+		const rows = [];
+		
+		// top spacer for rows before visible range
+		if (start > 0) {
+			const tr = document.createElement('tr');
+			tr.style.height = `${start * this.rowHeight}px`;
+			rows.push(tr);
+		}
+		
+		// visible rows with alternating stripe class
+		for (let i = start; i < end; i++) {
+			const row = this.createRow(i);
+			if (i % 2 === 1) row.classList.add(STRIPE_CLASS);
+			rows.push(row);
+		}
+		
+		// bottom spacer for rows after visible range
+		if (end < this.itemCount) {
+			const tr = document.createElement('tr');
+			tr.style.height = `${(this.itemCount - end) * this.rowHeight}px`;
+			rows.push(tr);
+		}
+		
+		this.tbody.replaceChildren(...rows);
+		this.onScroll?.();
+	}
+	
+	// update item count and re-render with fresh data
+	updateItemCount(itemCount) {
+		this.itemCount = itemCount;
+		this.render(true);
+	}
+	
+	// clean up event listeners and cancel pending renders
+	destroy() {
+		cancelAnimationFrame(this.rafId);
+		clearTimeout(this.resizeTimeout);
+		this.container.removeEventListener('scroll', this.handleScroll);
+		window.removeEventListener('resize', this.handleResize);
+	}
+}