From 5fdcf8cb56ceb7e6daa05b94fbe8d47350fcffb1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 19 Jun 2026 14:00:56 +0000
Subject: [PATCH] perf(frontend): virtualize ResourceList rows (list view)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Large folders/collections rendered every row into the DOM, so memory and
scripting time grew linearly with item count. A 20k-row list took ~12.5s to
first paint, held ~380k DOM nodes / ~281MB JS heap, and scrolled at ~4fps.

Add a reusable, dependency-free `VirtualList` that windows rows against the
nearest scrollable ancestor (the existing `.content-area`), so the
single-scrollbar UX, sticky header and end-of-list sentinel are unchanged. It
reserves the full scroll height with a sized spacer and translates a small
window of rows; row height is auto-measured for the single-column case.

Wire it into ResourceList's flat list view (recent, favorites, shared,
shared-with-me, trash, search). Grouped sections and grid view are unchanged
for now and are the next callers of the same primitive.

Measured in headless Chromium (1280x900) with synthetic rows, before/after:

  rows  | mount→paint | DOM nodes | JS heap | scroll frame | jank frames
  ------+-------------+-----------+---------+--------------+------------
   1000 | 632→70 ms   | 19k→351   | 16→2 MB | 17→17 ms     | 0→0
   5000 | 4401→54 ms  | 95k→351   | 72→3 MB | 47→17 ms     | 136→0
  20000 | 12577→56 ms | 380k→351  |281→6 MB |258→17 ms     | 1443→0

Rendered DOM and heap are now flat (O(visible)) regardless of dataset size;
scroll holds 60fps with zero jank. Correctness verified by probing a mid-list
scroll (rows land at the expected indices, positioned within the viewport).

eslint: disable core `no-undef` for `.svelte` (TypeScript/svelte-check already
resolve identifiers, including `<script generics>` type params it can't see).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M8Vb9QHmLZnEMzHz7MrFy6
---
 frontend/.gitignore                           |   1 +
 frontend/.prettierignore                      |   1 +
 frontend/eslint.config.js                     |   7 +-
 .../src/lib/components/ResourceList.svelte    |   5 +
 .../src/lib/components/VirtualList.svelte     | 168 ++++++++++++++++++
 5 files changed, 181 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/lib/components/VirtualList.svelte

diff --git a/frontend/.gitignore b/frontend/.gitignore
index eda1f418..5b512e6e 100644
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -1,4 +1,5 @@
 node_modules/
+/bench/
 /build/
 /.svelte-kit/
 /package-lock.json.bak
diff --git a/frontend/.prettierignore b/frontend/.prettierignore
index dd38ec68..f0175abb 100644
--- a/frontend/.prettierignore
+++ b/frontend/.prettierignore
@@ -1,3 +1,4 @@
+bench/
 build/
 .svelte-kit/
 package/
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index 3d882973..cee95c4e 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -24,11 +24,16 @@ export default ts.config(
 			parserOptions: {
 				parser: ts.parser
 			}
+		},
+		// TypeScript + svelte-check already resolve identifiers (including `<script
+		// generics>` type params, which core `no-undef` can't see). Defer to them.
+		rules: {
+			'no-undef': 'off'
 		}
 	},
 	{
 		// `static/` holds vendored, verbatim assets (the delta-upload worker and
 		// the wasm-bindgen hash glue) — lint them as the upstream ships them.
-		ignores: ['build/', '.svelte-kit/', 'package/', 'static/']
+		ignores: ['build/', '.svelte-kit/', 'package/', 'static/', 'bench/']
 	}
 );
diff --git a/frontend/src/lib/components/ResourceList.svelte b/frontend/src/lib/components/ResourceList.svelte
index 742fcb86..14eb4024 100644
--- a/frontend/src/lib/components/ResourceList.svelte
+++ b/frontend/src/lib/components/ResourceList.svelte
@@ -54,6 +54,7 @@
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import SkeletonList from '$lib/components/SkeletonList.svelte';
 	import ListToolbar from '$lib/components/ListToolbar.svelte';
+	import VirtualList from '$lib/components/VirtualList.svelte';
 	import { t } from '$lib/i18n/index.svelte';
 	import { files as filesStore } from '$lib/stores/files.svelte';
 	import { formatBytes } from '$lib/utils/format';
@@ -437,6 +438,10 @@
 						{@render row(entry)}
 					{/each}
 				{/each}
+			{:else if filesStore.viewMode === 'list'}
+				<!-- Flat list view: only the visible rows are mounted. The spacer keeps
+				     the full scroll height so the end-of-list sentinel still fires. -->
+				<VirtualList {items} rowHeight={56} key={(e) => e.id} {row} />
 			{:else}
 				{#each items as entry (entry.id)}
 					{@render row(entry)}
diff --git a/frontend/src/lib/components/VirtualList.svelte b/frontend/src/lib/components/VirtualList.svelte
new file mode 100644
index 00000000..cd4ef1b9
--- /dev/null
+++ b/frontend/src/lib/components/VirtualList.svelte
@@ -0,0 +1,168 @@
+<script lang="ts" module>
+	/**
+	 * Generic windowing list. Renders only the rows intersecting the nearest
+	 * scrollable ancestor's viewport (plus an overscan margin), reserving the full
+	 * scroll height with a sized spacer so the scrollbar, sticky headers and any
+	 * end-of-list sentinel keep behaving exactly as with a fully-rendered list.
+	 *
+	 * Scroll-ancestor based (not its own scroll box) so it drops into the existing
+	 * `.content-area` layout without changing the single-scrollbar UX. Row height
+	 * is auto-measured for the single-column case; pass `rowHeight` as the estimate
+	 * (and for multi-column grids, where it must be the row pitch incl. gap).
+	 */
+	export interface VirtualListProps<T> {
+		items: T[];
+		/** Row pitch in px (height incl. row gap). Auto-refined when columns === 1. */
+		rowHeight?: number;
+		/** Items per row; > 1 lays the window out as a grid. */
+		columns?: number;
+		/** Extra rows rendered above and below the viewport. */
+		overscan?: number;
+		/** Class applied to the inner window (e.g. the grid container class). */
+		windowClass?: string;
+		/** Inline style applied to the inner window (e.g. grid-template-columns). */
+		windowStyle?: string;
+		/** Stable key per item (defaults to the absolute index). */
+		key?: (item: T, index: number) => string | number;
+		row: import('svelte').Snippet<[T, number]>;
+	}
+</script>
+
+<script lang="ts" generics="T">
+	import { onMount } from 'svelte';
+
+	let {
+		items,
+		rowHeight = 48,
+		columns = 1,
+		overscan = 6,
+		windowClass = '',
+		windowStyle = '',
+		key,
+		row
+	}: VirtualListProps<T> = $props();
+
+	let rootEl: HTMLDivElement;
+	/** Measured row pitch in px; 0 until known, then refined from a real row. */
+	let measuredRow = $state(0);
+	let firstRow = $state(0);
+	let lastRow = $state(0);
+
+	const cols = $derived(Math.max(1, columns));
+	const effRowH = $derived(measuredRow > 0 ? measuredRow : rowHeight);
+	const rowCount = $derived(Math.ceil(items.length / cols));
+	const totalHeight = $derived(rowCount * effRowH);
+	const startIndex = $derived(firstRow * cols);
+	const endIndex = $derived(Math.min(items.length, lastRow * cols));
+	const offsetY = $derived(firstRow * effRowH);
+	const visible = $derived(items.slice(startIndex, endIndex));
+
+	let scroller: HTMLElement | null = null;
+
+	/** Nearest scrollable ancestor, or null to mean the window/document. */
+	function findScroller(el: HTMLElement): HTMLElement | null {
+		let node = el.parentElement;
+		while (node) {
+			const oy = getComputedStyle(node).overflowY;
+			if (oy === 'auto' || oy === 'scroll' || oy === 'overlay') return node;
+			node = node.parentElement;
+		}
+		return null;
+	}
+
+	function viewportRect(): { top: number; height: number } {
+		if (scroller) {
+			const r = scroller.getBoundingClientRect();
+			return { top: r.top, height: scroller.clientHeight };
+		}
+		return { top: 0, height: window.innerHeight };
+	}
+
+	function measure(): void {
+		if (!rootEl) return;
+		const { top: vTop, height: vH } = viewportRect();
+		// How far the list's top has scrolled above the viewport top (px).
+		const aboveBy = vTop - rootEl.getBoundingClientRect().top;
+		const rh = effRowH || rowHeight;
+		firstRow = Math.max(0, Math.floor(aboveBy / rh) - overscan);
+		lastRow = Math.min(rowCount, Math.ceil((aboveBy + vH) / rh) + overscan);
+	}
+
+	let ticking = false;
+	function onScroll(): void {
+		if (ticking) return;
+		ticking = true;
+		requestAnimationFrame(() => {
+			ticking = false;
+			measure();
+		});
+	}
+
+	/** Single-column: adopt the real rendered row height once it's known. */
+	function refineRowHeight(): void {
+		if (cols !== 1 || !rootEl) return;
+		const firstChild = rootEl.querySelector('.vlist__window > *') as HTMLElement | null;
+		if (!firstChild) return;
+		const h = firstChild.getBoundingClientRect().height;
+		if (h > 0 && Math.abs(h - measuredRow) > 0.5) measuredRow = h;
+	}
+
+	onMount(() => {
+		scroller = findScroller(rootEl);
+		const target: EventTarget = scroller ?? window;
+		target.addEventListener('scroll', onScroll, { passive: true });
+		window.addEventListener('resize', onScroll, { passive: true });
+		const ro = new ResizeObserver(() => onScroll());
+		if (scroller) ro.observe(scroller);
+		ro.observe(rootEl);
+		measure();
+		requestAnimationFrame(() => {
+			refineRowHeight();
+			measure();
+		});
+		return () => {
+			target.removeEventListener('scroll', onScroll);
+			window.removeEventListener('resize', onScroll);
+			ro.disconnect();
+		};
+	});
+
+	// Re-window when the dataset size or column count changes (load-more, reload,
+	// viewport breakpoint). `effRowH` is read so a refined height re-runs it too.
+	$effect(() => {
+		void items.length;
+		void cols;
+		void effRowH;
+		measure();
+	});
+
+	// Refine the measured row height once rows are actually in the DOM.
+	$effect(() => {
+		void visible.length;
+		refineRowHeight();
+	});
+</script>
+
+<div bind:this={rootEl} class="vlist" style:height="{totalHeight}px">
+	<div
+		class="vlist__window {windowClass}"
+		style="transform: translateY({offsetY}px); {windowStyle}"
+	>
+		{#each visible as item, i (key ? key(item, startIndex + i) : startIndex + i)}
+			{@render row(item, startIndex + i)}
+		{/each}
+	</div>
+</div>
+
+<style>
+	.vlist {
+		position: relative;
+		width: 100%;
+	}
+
+	.vlist__window {
+		position: absolute;
+		inset: 0 0 auto;
+		will-change: transform;
+	}
+</style>