From 34eae35becb705bc269fc9a831f9c64deefebc4f Mon Sep 17 00:00:00 2001
From: Mattias Granlund <mtsgrd@gmail.com>
Date: Thu, 27 Nov 2025 13:23:33 +0200
Subject: [PATCH] Use VirtualList for commits and file list

Replace manual iteration with VirtualList in BranchCommitList and
FileList to improve performance with large lists. Create
ConfigurableVirtualList wrapper that applies user's scrollbar
visibility preference. Implement tree flattening for virtual scrolling
in tree mode with expand/collapse support.

- Add ConfigurableVirtualList component wrapping VirtualList with user
  settings
- Add flattenTree() to convert tree structure to flat list for virtual
  rendering
- Add max-height constraint to commit list container
- Remove transition from CommitRow to prevent scroll performance issues
---
 .../src/components/BranchCommitList.svelte    | 390 +++++++++---------
 apps/desktop/src/components/CommitRow.svelte  |   3 +-
 .../components/ConfigurableVirtualList.svelte |  63 +++
 apps/desktop/src/components/FileList.svelte   | 115 ++++--
 apps/desktop/src/lib/files/filetreeV3.ts      |  77 ++++
 packages/ui/src/lib/index.ts                  |   1 +
 6 files changed, 431 insertions(+), 218 deletions(-)
 create mode 100644 apps/desktop/src/components/ConfigurableVirtualList.svelte

diff --git a/apps/desktop/src/components/BranchCommitList.svelte b/apps/desktop/src/components/BranchCommitList.svelte
index 12df1917f9..fd2b11c285 100644
--- a/apps/desktop/src/components/BranchCommitList.svelte
+++ b/apps/desktop/src/components/BranchCommitList.svelte
@@ -4,6 +4,7 @@
 	import CommitContextMenu from '$components/CommitContextMenu.svelte';
 	import CommitGoesHere from '$components/CommitGoesHere.svelte';
 	import CommitRow from '$components/CommitRow.svelte';
+	import ConfigurableVirtualList from '$components/ConfigurableVirtualList.svelte';
 	import Dropzone from '$components/Dropzone.svelte';
 
 	import LineOverlay from '$components/LineOverlay.svelte';
@@ -230,30 +231,36 @@
 				use:focusable={{ vertical: true }}
 			>
 				{#if hasRemoteCommits}
-					{#each upstreamOnlyCommits as commit, i (commit.id)}
-						{@const first = i === 0}
-						{@const lastCommit = i === upstreamOnlyCommits.length - 1}
-						{@const selected = commit.id === selectedCommitId && branchName === selectedBranchName}
-						{@const commitId = commit.id}
-						{#if !isCommitting}
-							<CommitRow
-								type="Remote"
-								{stackId}
-								{commitId}
-								commitMessage={commit.message}
-								createdAt={commitCreatedAt(commit)}
-								tooltip="Upstream"
-								{branchName}
-								{first}
-								{lastCommit}
-								{selected}
-								{active}
-								onclick={() => handleCommitClick(commit.id, true)}
-								disableCommitActions={false}
-								editable={!!stackId}
-							/>
-						{/if}
-					{/each}
+					{#if !isCommitting}
+						<ConfigurableVirtualList items={upstreamOnlyCommits} batchSize={10} defaultHeight={56}>
+							{#snippet chunkTemplate(chunk: typeof upstreamOnlyCommits)}
+								{#each chunk as commit}
+									{@const absoluteIndex = upstreamOnlyCommits.indexOf(commit)}
+									{@const first = absoluteIndex === 0}
+									{@const lastCommit = absoluteIndex === upstreamOnlyCommits.length - 1}
+									{@const selected =
+										commit.id === selectedCommitId && branchName === selectedBranchName}
+									{@const commitId = commit.id}
+									<CommitRow
+										type="Remote"
+										{stackId}
+										{commitId}
+										commitMessage={commit.message}
+										createdAt={commitCreatedAt(commit)}
+										tooltip="Upstream"
+										{branchName}
+										{first}
+										{lastCommit}
+										{selected}
+										{active}
+										onclick={() => handleCommitClick(commit.id, true)}
+										disableCommitActions={false}
+										editable={!!stackId}
+									/>
+								{/each}
+							{/snippet}
+						</ConfigurableVirtualList>
+					{/if}
 
 					<UpstreamCommitsAction testId={TestId.UpstreamCommitsCommitAction} isLast={!hasCommits}>
 						{#snippet action()}
@@ -264,173 +271,181 @@
 					</UpstreamCommitsAction>
 				{/if}
 
-				{#each localAndRemoteCommits as commit, i (commit.id)}
-					{@const first = i === 0}
-					{@const last = i === localAndRemoteCommits.length - 1}
-					{@const commitId = commit.id}
-					{@const selected = commit.id === selectedCommitId && branchName === selectedBranchName}
-					{#if isCommitting}
-						<!-- Only commits to the base can be `last`, see next `CommitGoesHere`. -->
-						<CommitGoesHere
-							{commitId}
-							selected={(commitAction?.parentCommitId === commitId ||
-								(first && commitAction?.parentCommitId === undefined)) &&
-								commitAction?.branchName === branchName}
-							{first}
-							last={false}
-							onclick={() => {
-								projectState.exclusiveAction.set({
-									type: 'commit',
-									stackId,
-									branchName,
-									parentCommitId: commitId
-								});
-							}}
-						/>
-					{/if}
-					{@const dzCommit: DzCommitData = {
-						id: commit.id,
-						isRemote: isUpstreamCommit(commit),
-						isIntegrated: isLocalAndRemoteCommit(commit) && commit.state.type === 'Integrated',
-						hasConflicts: isLocalAndRemoteCommit(commit) && commit.hasConflicts,
-					}}
-					{@const amendHandler = stackId
-						? new AmendCommitWithChangeDzHandler(
-								projectId,
-								stackService,
-								hooksService,
-								stackId,
-								$runHooks,
-								dzCommit,
-								(newId) => {
-									const previewOpen = selection.current?.previewOpen ?? false;
-									uiState.lane(stackId).selection.set({ branchName, commitId: newId, previewOpen });
-								},
-								uiState
-							)
-						: undefined}
-					{@const squashHandler = stackId
-						? new SquashCommitDzHandler({
-								stackService,
-								projectId,
-								stackId,
-								commit: dzCommit
-							})
-						: undefined}
-					{@const hunkHandler = stackId
-						? new AmendCommitWithHunkDzHandler({
-								stackService,
-								hooksService,
-								projectId,
-								stackId,
-								commit: dzCommit,
-								runHooks: $runHooks,
-								// TODO: Use correct value!
-								okWithForce: true,
-								uiState
-							})
-						: undefined}
-					{@const tooltip = commitStatusLabel(commit.state.type)}
-					<Dropzone handlers={[amendHandler, squashHandler, hunkHandler].filter(isDefined)}>
-						{#snippet overlay({ hovered, activated, handler })}
-							{@const label =
-								handler instanceof AmendCommitWithChangeDzHandler ||
-								handler instanceof AmendCommitWithHunkDzHandler
-									? 'Amend'
-									: 'Squash'}
-							<CardOverlay {hovered} {activated} {label} />
-						{/snippet}
-						<div
-							data-remove-from-panning
-							use:draggableCommitV3={{
-								disabled: false,
-								label: commit.message.split('\n')[0],
-								sha: commit.id.slice(0, 7),
-								date: getTimeAgo(commitCreatedAt(commit)),
-								authorImgUrl: undefined,
-								commitType: commit.state.type,
-								data: stackId
-									? new CommitDropData(
+				<ConfigurableVirtualList items={localAndRemoteCommits} batchSize={10} defaultHeight={56}>
+					{#snippet chunkTemplate(chunk: typeof localAndRemoteCommits)}
+						{#each chunk as commit}
+							{@const absoluteIndex = localAndRemoteCommits.indexOf(commit)}
+							{@const first = absoluteIndex === 0}
+							{@const last = absoluteIndex === localAndRemoteCommits.length - 1}
+							{@const commitId = commit.id}
+							{@const selected =
+								commit.id === selectedCommitId && branchName === selectedBranchName}
+							{#if isCommitting}
+								<!-- Only commits to the base can be `last`, see next `CommitGoesHere`. -->
+								<CommitGoesHere
+									{commitId}
+									selected={(commitAction?.parentCommitId === commitId ||
+										(first && commitAction?.parentCommitId === undefined)) &&
+										commitAction?.branchName === branchName}
+									{first}
+									last={false}
+									onclick={() => {
+										projectState.exclusiveAction.set({
+											type: 'commit',
 											stackId,
-											{
-												id: commitId,
-												isRemote: !!branchDetails.remoteTrackingBranch,
-												hasConflicts: isLocalAndRemoteCommit(commit) && commit.hasConflicts,
-												isIntegrated:
-													isLocalAndRemoteCommit(commit) && commit.state.type === 'Integrated'
-											},
-											false,
-											branchName
-										)
-									: undefined,
-								viewportId: 'board-viewport',
-								dropzoneRegistry,
-								dragStateService
+											branchName,
+											parentCommitId: commitId
+										});
+									}}
+								/>
+							{/if}
+							{@const dzCommit: DzCommitData = {
+								id: commit.id,
+								isRemote: isUpstreamCommit(commit),
+								isIntegrated: isLocalAndRemoteCommit(commit) && commit.state.type === 'Integrated',
+								hasConflicts: isLocalAndRemoteCommit(commit) && commit.hasConflicts,
 							}}
-						>
-							<CommitRow
-								commitId={commit.id}
-								commitMessage={commit.message}
-								type={commit.state.type}
-								hasConflicts={commit.hasConflicts}
-								diverged={commit.state.type === 'LocalAndRemote' &&
-									commit.id !== commit.state.subject}
-								createdAt={commitCreatedAt(commit)}
-								gerritReviewUrl={commit.gerritReviewUrl ?? undefined}
-								{stackId}
-								{branchName}
-								{first}
-								lastCommit={last}
-								{lastBranch}
-								{selected}
-								{tooltip}
-								{active}
-								onclick={() => handleCommitClick(commit.id, false)}
-								disableCommitActions={false}
-								editable={!!stackId}
-							>
-								{#snippet menu({ rightClickTrigger })}
-									{@const data = {
+							{@const amendHandler = stackId
+								? new AmendCommitWithChangeDzHandler(
+										projectId,
+										stackService,
+										hooksService,
 										stackId,
-										commitId,
-										commitMessage: commit.message,
-										commitStatus: commit.state.type,
-										commitUrl: forge.current.commitUrl(commitId),
-										onUncommitClick: () => handleUncommit(commit.id, branchName),
-										onEditMessageClick: () => startEditingCommitMessage(branchName, commit.id)
-									}}
-									<CommitContextMenu
-										showOnHover
-										{projectId}
-										{rightClickTrigger}
-										contextData={data}
-									/>
+										$runHooks,
+										dzCommit,
+										(newId) => {
+											const previewOpen = selection.current?.previewOpen ?? false;
+											uiState
+												.lane(stackId)
+												.selection.set({ branchName, commitId: newId, previewOpen });
+										},
+										uiState
+									)
+								: undefined}
+							{@const squashHandler = stackId
+								? new SquashCommitDzHandler({
+										stackService,
+										projectId,
+										stackId,
+										commit: dzCommit
+									})
+								: undefined}
+							{@const hunkHandler = stackId
+								? new AmendCommitWithHunkDzHandler({
+										stackService,
+										hooksService,
+										projectId,
+										stackId,
+										commit: dzCommit,
+										runHooks: $runHooks,
+										// TODO: Use correct value!
+										okWithForce: true,
+										uiState
+									})
+								: undefined}
+							{@const tooltip = commitStatusLabel(commit.state.type)}
+							<Dropzone handlers={[amendHandler, squashHandler, hunkHandler].filter(isDefined)}>
+								{#snippet overlay({ hovered, activated, handler })}
+									{@const label =
+										handler instanceof AmendCommitWithChangeDzHandler ||
+										handler instanceof AmendCommitWithHunkDzHandler
+											? 'Amend'
+											: 'Squash'}
+									<CardOverlay {hovered} {activated} {label} />
 								{/snippet}
-							</CommitRow>
-						</div>
-					</Dropzone>
-					{@render commitReorderDz(
-						stackingReorderDropzoneManager.belowCommit(branchName, commit.id)
-					)}
-					{#if isCommitting && last}
-						<CommitGoesHere
-							commitId={branchDetails.baseCommit}
-							{first}
-							{last}
-							selected={exclusiveAction?.type === 'commit' &&
-								exclusiveAction.parentCommitId === branchDetails.baseCommit &&
-								commitAction?.branchName === branchName}
-							onclick={() => {
-								projectState.exclusiveAction.set({
-									type: 'commit',
-									stackId,
-									branchName,
-									parentCommitId: branchDetails.baseCommit
-								});
-							}}
-						/>
-					{/if}
-				{/each}
+								<div
+									data-remove-from-panning
+									use:draggableCommitV3={{
+										disabled: false,
+										label: commit.message.split('\n')[0],
+										sha: commit.id.slice(0, 7),
+										date: getTimeAgo(commitCreatedAt(commit)),
+										authorImgUrl: undefined,
+										commitType: commit.state.type,
+										data: stackId
+											? new CommitDropData(
+													stackId,
+													{
+														id: commitId,
+														isRemote: !!branchDetails.remoteTrackingBranch,
+														hasConflicts: isLocalAndRemoteCommit(commit) && commit.hasConflicts,
+														isIntegrated:
+															isLocalAndRemoteCommit(commit) && commit.state.type === 'Integrated'
+													},
+													false,
+													branchName
+												)
+											: undefined,
+										viewportId: 'board-viewport',
+										dropzoneRegistry,
+										dragStateService
+									}}
+								>
+									<CommitRow
+										commitId={commit.id}
+										commitMessage={commit.message}
+										type={commit.state.type}
+										hasConflicts={commit.hasConflicts}
+										diverged={commit.state.type === 'LocalAndRemote' &&
+											commit.id !== commit.state.subject}
+										createdAt={commitCreatedAt(commit)}
+										gerritReviewUrl={commit.gerritReviewUrl ?? undefined}
+										{stackId}
+										{branchName}
+										{first}
+										lastCommit={last}
+										{lastBranch}
+										{selected}
+										{tooltip}
+										{active}
+										onclick={() => handleCommitClick(commit.id, false)}
+										disableCommitActions={false}
+										editable={!!stackId}
+									>
+										{#snippet menu({ rightClickTrigger })}
+											{@const data = {
+												stackId,
+												commitId,
+												commitMessage: commit.message,
+												commitStatus: commit.state.type,
+												commitUrl: forge.current.commitUrl(commitId),
+												onUncommitClick: () => handleUncommit(commit.id, branchName),
+												onEditMessageClick: () => startEditingCommitMessage(branchName, commit.id)
+											}}
+											<CommitContextMenu
+												showOnHover
+												{projectId}
+												{rightClickTrigger}
+												contextData={data}
+											/>
+										{/snippet}
+									</CommitRow>
+								</div>
+							</Dropzone>
+							{@render commitReorderDz(
+								stackingReorderDropzoneManager.belowCommit(branchName, commit.id)
+							)}
+							{#if isCommitting && last}
+								<CommitGoesHere
+									commitId={branchDetails.baseCommit}
+									{first}
+									{last}
+									selected={exclusiveAction?.type === 'commit' &&
+										exclusiveAction.parentCommitId === branchDetails.baseCommit &&
+										commitAction?.branchName === branchName}
+									onclick={() => {
+										projectState.exclusiveAction.set({
+											type: 'commit',
+											stackId,
+											branchName,
+											parentCommitId: branchDetails.baseCommit
+										});
+									}}
+								/>
+							{/if}
+						{/each}
+					{/snippet}
+				</ConfigurableVirtualList>
 			</div>
 		{/if}
 	{/snippet}
@@ -441,6 +456,7 @@
 		display: flex;
 		position: relative;
 		flex-direction: column;
+		max-height: 370px;
 		overflow: hidden;
 		border: 1px solid var(--clr-border-2);
 		border-radius: 0 0 var(--radius-ml) var(--radius-ml);
diff --git a/apps/desktop/src/components/CommitRow.svelte b/apps/desktop/src/components/CommitRow.svelte
index aafdbdd377..5ec2a29abd 100644
--- a/apps/desktop/src/components/CommitRow.svelte
+++ b/apps/desktop/src/components/CommitRow.svelte
@@ -201,7 +201,8 @@
 		overflow: hidden;
 		outline: none;
 		background-color: var(--clr-bg-1);
-		transition: background-color var(--transition-fast);
+		/* Incompatible with virtual scroll, scroll thumb becomes laggy. */
+		/* transition: background-color var(--transition-fast); */
 
 		&:hover,
 		&.menu-shown {
diff --git a/apps/desktop/src/components/ConfigurableVirtualList.svelte b/apps/desktop/src/components/ConfigurableVirtualList.svelte
new file mode 100644
index 0000000000..bbe19730de
--- /dev/null
+++ b/apps/desktop/src/components/ConfigurableVirtualList.svelte
@@ -0,0 +1,63 @@
+<script lang="ts" module>
+	type T = unknown;
+</script>
+
+<script lang="ts" generics="T">
+	import { SETTINGS } from '$lib/settings/userSettings';
+	import { inject } from '@gitbutler/core/context';
+	import { VirtualList } from '@gitbutler/ui';
+	import type { Snippet } from 'svelte';
+
+	type Props = {
+		items: Array<T>;
+		children?: Snippet<[]>;
+		chunkTemplate: Snippet<[T[]]>;
+		batchSize: number;
+		onloadmore?: () => Promise<void>;
+		grow?: boolean;
+		stickToBottom?: boolean;
+		defaultHeight: number;
+		padding?: {
+			left?: number;
+			right?: number;
+			top?: number;
+			bottom?: number;
+		};
+	};
+
+	const {
+		items,
+		children,
+		chunkTemplate,
+		batchSize,
+		onloadmore,
+		grow,
+		padding,
+		defaultHeight,
+		stickToBottom = false
+	}: Props = $props();
+
+	const userSettings = inject(SETTINGS);
+	let virtualList: VirtualList<T>;
+
+	// Export method to scroll to bottom
+	export function scrollToBottom() {
+		if (virtualList?.scrollToBottom) {
+			virtualList.scrollToBottom();
+		}
+	}
+</script>
+
+<VirtualList
+	bind:this={virtualList}
+	{items}
+	{batchSize}
+	{defaultHeight}
+	visibility={$userSettings.scrollbarVisibilityState}
+	{grow}
+	{stickToBottom}
+	{onloadmore}
+	{padding}
+	{chunkTemplate}
+	{children}
+/>
diff --git a/apps/desktop/src/components/FileList.svelte b/apps/desktop/src/components/FileList.svelte
index e097ae4f5d..2d849707d8 100644
--- a/apps/desktop/src/components/FileList.svelte
+++ b/apps/desktop/src/components/FileList.svelte
@@ -1,9 +1,10 @@
 <!-- This is a V3 replacement for `BranchFileList.svelte` -->
 <script lang="ts">
+	import ConfigurableVirtualList from '$components/ConfigurableVirtualList.svelte';
 	import EditPatchConfirmModal from '$components/EditPatchConfirmModal.svelte';
 	import FileListItemWrapper from '$components/FileListItemWrapper.svelte';
-	import FileTreeNode from '$components/FileTreeNode.svelte';
 	import LazyloadContainer from '$components/LazyloadContainer.svelte';
+	import TreeListFolder from '$components/TreeListFolder.svelte';
 	import { ACTION_SERVICE } from '$lib/actions/actionService.svelte';
 	import { AI_SERVICE } from '$lib/ai/service';
 	import { projectAiGenEnabled } from '$lib/config/config';
@@ -15,7 +16,13 @@
 	} from '$lib/dependencies/dependencies';
 	import { DEPENDENCY_SERVICE } from '$lib/dependencies/dependencyService.svelte';
 	import { editPatch } from '$lib/editMode/editPatchUtils';
-	import { abbreviateFolders, changesToFileTree } from '$lib/files/filetreeV3';
+	import {
+		abbreviateFolders,
+		changesToFileTree,
+		flattenTree,
+		nodePath,
+		type TreeNode
+	} from '$lib/files/filetreeV3';
 	import { type TreeChange, isExecutableStatus } from '$lib/hunks/change';
 	import { MODE_SERVICE } from '$lib/mode/modeService';
 	import { showToast } from '$lib/notifications/toasts';
@@ -75,6 +82,9 @@
 	let editPatchModal: EditPatchConfirmModal | undefined = $state();
 	let selectedFilePath = $state('');
 
+	// Track which folders are expanded in tree mode
+	let expandedFolders = $state<Set<string>>(new Set());
+
 	const filePaths = $derived(changes.map((change) => change.path));
 	const fileDependenciesQuery = $derived(
 		showLockedIndicator ? dependencyService.filesDependencies(projectId, filePaths) : null
@@ -106,6 +116,44 @@
 	let aiConfigurationValid = $state(false);
 	let active = $state(false);
 
+	// Compute flattened tree structure for tree mode
+	const treeNode = $derived(
+		listMode === 'tree' ? abbreviateFolders(changesToFileTree(changes)) : null
+	);
+	const flattenedItems = $derived(treeNode ? flattenTree(treeNode, expandedFolders) : []);
+
+	function toggleFolder(nodeId: string) {
+		const newSet = new Set(expandedFolders);
+		if (newSet.has(nodeId)) {
+			newSet.delete(nodeId);
+		} else {
+			newSet.add(nodeId);
+		}
+		expandedFolders = newSet;
+	}
+
+	// Initialize all folders as expanded
+	function collectAllFolderIds(node: TreeNode): string[] {
+		const ids: string[] = [];
+		for (const child of node.children) {
+			if (child.kind === 'dir') {
+				const nodeId = nodePath(child);
+				if (nodeId) {
+					ids.push(nodeId);
+					ids.push(...collectAllFolderIds(child));
+				}
+			}
+		}
+		return ids;
+	}
+
+	$effect(() => {
+		if (treeNode && listMode === 'tree') {
+			const folderIds = collectAllFolderIds(treeNode);
+			expandedFolders = new Set(folderIds);
+		}
+	});
+
 	const aiGenEnabled = $derived(projectAiGenEnabled(projectId));
 
 	const canUseGBAI = $derived(aiGenEnabled && aiConfigurationValid);
@@ -347,35 +395,42 @@
 	</div>
 
 	<!-- Other changes -->
-	{#if visibleFiles.length > 0}
-		{#if listMode === 'tree'}
-			<!-- We need to use sortedChanges here because otherwise we will end up
-		with incorrect indexes -->
-			{@const node = abbreviateFolders(changesToFileTree(changes))}
-			<FileTreeNode
-				isRoot
-				{projectId}
-				{selectionId}
-				{stackId}
-				{node}
-				{showCheckboxes}
-				{draggableFiles}
-				{changes}
-				{fileTemplate}
-			/>
-		{:else}
-			<LazyloadContainer
-				minTriggerCount={80}
-				ontrigger={() => {
-					loadMore();
-				}}
-				role="listbox"
-			>
-				{#each visibleFiles as change, idx}
-					{@render fileTemplate(change, idx)}
+	{#if listMode === 'tree' && flattenedItems.length > 0}
+		<ConfigurableVirtualList items={flattenedItems} batchSize={20} defaultHeight={32} grow={false}>
+			{#snippet chunkTemplate(chunk)}
+				{#each chunk as item}
+					{#if item.type === 'folder'}
+						{@const dirNode = item.node as TreeNode & { kind: 'dir' }}
+						<TreeListFolder
+							{projectId}
+							{stackId}
+							{selectionId}
+							testId={TestId.FileListTreeFolder}
+							depth={item.depth}
+							isExpanded={item.isExpanded}
+							showCheckbox={showCheckboxes}
+							draggable={draggableFiles}
+							node={dirNode}
+							ontoggle={() => toggleFolder(item.nodeId)}
+						/>
+					{:else}
+						{@render fileTemplate(item.change, item.index, item.depth)}
+					{/if}
 				{/each}
-			</LazyloadContainer>
-		{/if}
+			{/snippet}
+		</ConfigurableVirtualList>
+	{:else if listMode === 'list' && visibleFiles.length > 0}
+		<LazyloadContainer
+			minTriggerCount={80}
+			ontrigger={() => {
+				loadMore();
+			}}
+			role="listbox"
+		>
+			{#each visibleFiles as change, idx}
+				{@render fileTemplate(change, idx)}
+			{/each}
+		</LazyloadContainer>
 	{/if}
 </div>
 
diff --git a/apps/desktop/src/lib/files/filetreeV3.ts b/apps/desktop/src/lib/files/filetreeV3.ts
index ee71b8d265..1719dd3fc1 100644
--- a/apps/desktop/src/lib/files/filetreeV3.ts
+++ b/apps/desktop/src/lib/files/filetreeV3.ts
@@ -170,3 +170,80 @@ export function getAllChanges(node: TreeNode): TreeChange[] {
 	}
 	return node.children.reduce((prev, curr) => prev.concat(getAllChanges(curr)), [] as TreeChange[]);
 }
+
+/**
+ * Represents a flattened tree item that can be rendered in a virtual list.
+ */
+export type FlatTreeItem =
+	| {
+			type: 'folder';
+			name: string;
+			depth: number;
+			node: TreeNode;
+			nodeId: string;
+			isExpanded: boolean;
+	  }
+	| {
+			type: 'file';
+			name: string;
+			depth: number;
+			change: TreeChange;
+			index: number;
+			nodeId: string;
+	  };
+
+/**
+ * Generates a unique ID for a tree node based on its path.
+ */
+function getNodeId(node: TreeNode): string {
+	return nodePath(node) || 'root';
+}
+
+/**
+ * Flattens a tree structure into a linear array suitable for virtual scrolling.
+ * Only includes items that should be visible based on expanded state.
+ *
+ * @param node - The tree node to flatten
+ * @param expandedFolders - Set of folder IDs that are currently expanded
+ * @param depth - Current depth in the tree (for indentation)
+ * @returns Array of flattened items ready for rendering
+ */
+export function flattenTree(
+	node: TreeNode,
+	expandedFolders: Set<string>,
+	depth: number = 0
+): FlatTreeItem[] {
+	const items: FlatTreeItem[] = [];
+
+	for (const child of node.children) {
+		const nodeId = getNodeId(child);
+
+		if (child.kind === 'file') {
+			items.push({
+				type: 'file',
+				name: child.name,
+				depth,
+				change: child.change,
+				index: child.index,
+				nodeId
+			});
+		} else {
+			const isExpanded = expandedFolders.has(nodeId);
+			items.push({
+				type: 'folder',
+				name: child.name,
+				depth,
+				node: child,
+				nodeId,
+				isExpanded
+			});
+
+			// Only include children if this folder is expanded
+			if (isExpanded) {
+				items.push(...flattenTree(child, expandedFolders, depth + 1));
+			}
+		}
+	}
+
+	return items;
+}
diff --git a/packages/ui/src/lib/index.ts b/packages/ui/src/lib/index.ts
index 790a0c27c7..50b06fc063 100644
--- a/packages/ui/src/lib/index.ts
+++ b/packages/ui/src/lib/index.ts
@@ -53,6 +53,7 @@ export { default as TimeAgo } from '$components/TimeAgo.svelte';
 export { default as Timestamp } from '$components/Timestamp.svelte';
 export { default as Toggle } from '$components/Toggle.svelte';
 export { default as Tooltip } from '$components/Tooltip.svelte';
+export { default as VirtualList } from '$components/VirtualList.svelte';
 
 // ChipToast Components
 export { default as ChipToast } from '$components/chipToast/ChipToast.svelte';