@hienlh/ppm 0.17.40 → 0.17.42

package/src/web/components/explorer/tree-node.tsx

@@ -1,5 +1,6 @@
 /**
- * TreeNode component — renders a single file/folder row in the explorer tree.
+ * TreeRow component — renders a single file/folder row in the virtualized explorer tree.
+ * Rows are flat siblings (no recursion); visible order comes from flatten-visible-tree.ts.
  * Handles click, drag/drop, context menu for individual tree items.
  */
 import { useState, useRef, useEffect, memo } from "react";
@@ -11,37 +12,41 @@ import {
   Loader2,
 } from "lucide-react";
 import { useShallow } from "zustand/react/shallow";
-import { useFileStore, getVisiblePaths, type FileNode, type InlineAction } from "@/stores/file-store";
+import { useFileStore, getVisiblePaths, type FileNode } from "@/stores/file-store";
 import { useTabStore } from "@/stores/tab-store";
 import { useCompareStore } from "@/stores/compare-store";
 import { useGitStatusStore, GIT_STATUS_COLORS, type GitFileStatus } from "@/stores/git-status-store";
 import { api, projectUrl } from "@/lib/api-client";
 import { cn } from "@/lib/utils";
 import { toast } from "sonner";
-import { InlineTreeInput } from "./inline-tree-input";
 import {
   ContextMenu,
   ContextMenuTrigger,
 } from "@/components/ui/adaptive-context-menu";
 import { getFileIcon } from "./file-icon-map";
 import { TreeNodeContextMenu } from "./tree-node-context-menu";
+import type { NodeRow } from "./flatten-visible-tree";
 
 /** Check if drag event is from OS files (not internal PPM drag) */
 export function isExternalFileDrag(e: React.DragEvent): boolean {
   return e.dataTransfer.types.includes("Files") && !e.dataTransfer.types.includes("application/x-ppm-path");
 }
 
-export interface TreeNodeProps {
-  node: FileNode;
-  depth: number;
+function parentDirOf(path: string): string {
+  return path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+}
+
+export interface TreeRowProps {
+  row: NodeRow;
   projectName: string;
   onAction: (action: string, node: FileNode) => void;
   onFileDrop: (targetDir: string, files: FileList) => void;
   onFileOpen?: () => void;
 }
 
-export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAction, onFileDrop, onFileOpen }: TreeNodeProps) {
-  const { expandedPaths, loadedPaths, inflight, toggleExpand, selectedFiles, toggleFileSelect, inlineAction, clearInlineAction, clipboard, focusedPath, setFocusedPath } = useFileStore(
+export const TreeRow = memo(function TreeRow({ row, projectName, onAction, onFileDrop, onFileOpen }: TreeRowProps) {
+  const { node, effectiveNode, displayName, depth } = row;
+  const { expandedPaths, loadedPaths, inflight, toggleExpand, selectedFiles, toggleFileSelect, clipboard, focusedPath, setFocusedPath } = useFileStore(
     useShallow((s) => ({
       expandedPaths: s.expandedPaths,
       loadedPaths: s.loadedPaths,
@@ -49,8 +54,6 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
       toggleExpand: s.toggleExpand,
       selectedFiles: s.selectedFiles,
       toggleFileSelect: s.toggleFileSelect,
-      inlineAction: s.inlineAction,
-      clearInlineAction: s.clearInlineAction,
       clipboard: s.clipboard,
       focusedPath: s.focusedPath,
       setFocusedPath: s.setFocusedPath,
@@ -69,8 +72,8 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
   const isSelected = selectedFiles.includes(node.path);
   const isIgnored = node.ignored === true;
   const isCut = clipboard?.operation === "cut" && clipboard.paths.includes(node.path);
-  const isFocused = focusedPath === node.path;
-  const isLoadingChildren = isDir && isExpanded && !loadedPaths.has(node.path) && inflight.has(node.path);
+  const isFocused = focusedPath === node.path || focusedPath === effectiveNode.path;
+  const isLoadingChildren = isDir && isExpanded && !loadedPaths.has(effectiveNode.path) && inflight.has(effectiveNode.path);
   const [isDragOver, setIsDragOver] = useState(false);
   const dragCounter = useRef(0);
   const rowRef = useRef<HTMLButtonElement>(null);
@@ -92,7 +95,7 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     if (e.shiftKey && focusedPath != null) {
       const paths = getVisiblePaths();
       const fromIdx = paths.indexOf(focusedPath);
-      const toIdx = paths.indexOf(node.path);
+      const toIdx = paths.indexOf(effectiveNode.path);
       if (fromIdx >= 0 && toIdx >= 0) {
         const start = Math.min(fromIdx, toIdx);
         const end = Math.max(fromIdx, toIdx);
@@ -126,9 +129,10 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     e.dataTransfer.effectAllowed = "copyMove";
   }
 
-  /** Accept both external file drops and internal tree moves on directories */
+  // Flat rows: dropping on a file targets its parent directory
+  const dropTargetDir = isDir ? effectiveNode.path : parentDirOf(node.path);
+
   function canAcceptDrop(e: React.DragEvent): boolean {
-    if (!isDir) return false;
     return isExternalFileDrag(e) || e.dataTransfer.types.includes("application/x-ppm-path");
   }
 
@@ -140,7 +144,6 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     if (dragCounter.current === 1) setIsDragOver(true);
   }
   function handleNodeDragLeave(e: React.DragEvent) {
-    if (!isDir) return;
     e.stopPropagation();
     dragCounter.current--;
     if (dragCounter.current === 0) setIsDragOver(false);
@@ -152,7 +155,6 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     e.dataTransfer.dropEffect = isExternalFileDrag(e) ? "copy" : "move";
   }
   function handleNodeDrop(e: React.DragEvent) {
-    if (!isDir) return;
     e.preventDefault();
     e.stopPropagation();
     dragCounter.current = 0;
@@ -160,7 +162,7 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
 
     // External file upload
     if (isExternalFileDrag(e)) {
-      if (e.dataTransfer.files.length > 0) onFileDrop(node.path, e.dataTransfer.files);
+      if (e.dataTransfer.files.length > 0) onFileDrop(dropTargetDir, e.dataTransfer.files);
       return;
     }
 
@@ -168,20 +170,20 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     const sourcePath = e.dataTransfer.getData("application/x-ppm-path").replace(/\/$/, "");
     if (!sourcePath) return;
     // Prevent dropping into self or descendant
-    if (sourcePath === node.path || node.path.startsWith(`${sourcePath}/`)) return;
+    if (sourcePath === dropTargetDir || dropTargetDir.startsWith(`${sourcePath}/`)) return;
     // Prevent no-op (already in this folder)
-    const sourceParent = sourcePath.includes("/") ? sourcePath.slice(0, sourcePath.lastIndexOf("/")) : "";
-    if (sourceParent === node.path) return;
+    const sourceParent = parentDirOf(sourcePath);
+    if (sourceParent === dropTargetDir) return;
 
     const sourceName = sourcePath.includes("/") ? sourcePath.slice(sourcePath.lastIndexOf("/") + 1) : sourcePath;
-    const destination = node.path ? `${node.path}/${sourceName}` : sourceName;
+    const destination = dropTargetDir ? `${dropTargetDir}/${sourceName}` : sourceName;
     api.post(`${projectUrl(projectName)}/files/move`, { source: sourcePath, destination })
       .then(() => {
         const store = useFileStore.getState();
         store.invalidateIndex();
         store.loadIndex(projectName);
         store.invalidateFolder(projectName, sourceParent);
-        store.invalidateFolder(projectName, node.path);
+        store.invalidateFolder(projectName, dropTargetDir);
       })
       .catch((err) => {
         toast.error(err instanceof Error ? err.message : "Move failed");
@@ -192,159 +194,73 @@ export const TreeNode = memo(function TreeNode({ node, depth, projectName, onAct
     ? { icon: isExpanded ? FolderOpen : Folder, color: isExpanded ? "text-primary" : "text-text-3" }
     : getFileIcon(node.name);
 
-  // Compact folders: collapse single-child dir chains into "a/b/c" display
-  let displayName = node.name;
-  let effectiveNode = node;
-  if (isDir && isExpanded && node.children) {
-    let current = node;
-    while (
-      current.children &&
-      current.children.length === 1 &&
-      current.children[0]!.type === "directory" &&
-      expandedPaths.has(current.children[0]!.path)
-    ) {
-      current = current.children[0]!;
-      displayName += `/${current.name}`;
-    }
-    if (current !== node) effectiveNode = current;
-  }
-
-  const sortedChildren = effectiveNode.children
-    ? [...effectiveNode.children].sort((a, b) => {
-        if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
-        return a.name.localeCompare(b.name);
-      })
-    : [];
-
-  const isRenaming = inlineAction?.type === "rename" && inlineAction.existingNode?.path === node.path;
-  const isCreatingHere = isDir && inlineAction != null && (inlineAction.parentPath === node.path || inlineAction.parentPath === effectiveNode.path) && inlineAction.type !== "rename";
-
   return (
     <div
-      onDragEnter={isDir ? handleNodeDragEnter : undefined}
-      onDragLeave={isDir ? handleNodeDragLeave : undefined}
-      onDragOver={isDir ? handleNodeDragOver : undefined}
-      onDrop={isDir ? handleNodeDrop : undefined}
+      onDragEnter={handleNodeDragEnter}
+      onDragLeave={handleNodeDragLeave}
+      onDragOver={handleNodeDragOver}
+      onDrop={handleNodeDrop}
     >
-      {isRenaming ? (
-        <InlineTreeInput
-          defaultValue={node.name}
-          placeholder={node.name}
-          depth={depth}
-          icon={isDir ? "folder" : "file"}
-          onConfirm={async (newName) => {
-            if (newName === node.name) { clearInlineAction(); return; }
-            const parentPath = node.path.includes("/")
-              ? node.path.slice(0, node.path.lastIndexOf("/"))
-              : "";
-            const newPath = parentPath ? `${parentPath}/${newName}` : newName;
-            await api.post(`${projectUrl(projectName)}/files/rename`, {
-              oldPath: node.path,
-              newPath,
-            });
-            clearInlineAction();
-            const store = useFileStore.getState();
-            store.invalidateIndex();
-            store.loadIndex(projectName);
-            store.invalidateFolder(projectName, parentPath);
-          }}
-          onCancel={clearInlineAction}
-        />
-      ) : (
-        <ContextMenu>
-          <ContextMenuTrigger asChild>
-            <button
-              ref={rowRef}
-              draggable
-              onDragStart={handleDragStart}
-              onClick={handleClick}
+      <ContextMenu>
+        <ContextMenuTrigger asChild>
+          <button
+            ref={rowRef}
+            draggable
+            onDragStart={handleDragStart}
+            onClick={handleClick}
+            className={cn(
+              "flex items-center w-full gap-1.5 px-2 py-1 rounded-[var(--rad-sm)] text-[13px]",
+              "min-h-[32px] md:min-h-[26px] hover:bg-surface-elevated transition-colors text-left",
+              "select-none",
+              (isIgnored || isCut) && "opacity-40",
+              isFocused && "bg-surface-elevated",
+              isSelected && "bg-accent-wash",
+              isDragOver && "ring-1 ring-dashed ring-primary bg-primary/10",
+            )}
+            style={{ paddingLeft: `${depth * 16 + 8}px` }}
+          >
+            {isDir ? (
+              isLoadingChildren ? (
+                <Loader2 className="size-3.5 shrink-0 text-text-subtle animate-spin" />
+              ) : isExpanded ? (
+                <ChevronDown className="size-3.5 shrink-0 text-text-subtle" />
+              ) : (
+                <ChevronRight className="size-3.5 shrink-0 text-text-subtle" />
+              )
+            ) : (
+              <span className="w-3.5 shrink-0" />
+            )}
+            <FileIcon
               className={cn(
-                "flex items-center w-full gap-1.5 px-2 py-1 rounded-[var(--rad-sm)] text-[13px]",
-                "min-h-[32px] md:min-h-[26px] hover:bg-surface-elevated transition-colors text-left",
-                "select-none",
-                (isIgnored || isCut) && "opacity-40",
-                isFocused && "bg-surface-elevated",
-                isSelected && "bg-accent-wash",
-                isDragOver && "ring-1 ring-dashed ring-primary bg-primary/10",
+                "size-4 shrink-0",
+                fileIconColor ?? "text-text-secondary",
               )}
-              style={{ paddingLeft: `${depth * 16 + 8}px` }}
-            >
-              {isDir ? (
-                isLoadingChildren ? (
-                  <Loader2 className="size-3.5 shrink-0 text-text-subtle animate-spin" />
-                ) : isExpanded ? (
-                  <ChevronDown className="size-3.5 shrink-0 text-text-subtle" />
-                ) : (
-                  <ChevronRight className="size-3.5 shrink-0 text-text-subtle" />
-                )
-              ) : (
-                <span className="w-3.5 shrink-0" />
+            />
+            <span
+              className={cn(
+                "truncate",
+                gitColor ?? (isSelected ? "text-text" : isDir && isExpanded ? "text-text font-medium" : "text-text-2"),
               )}
-              <FileIcon
-                className={cn(
-                  "size-4 shrink-0",
-                  fileIconColor ?? "text-text-secondary",
-                )}
-              />
-              <span
-                className={cn(
-                  "truncate",
-                  gitColor ?? (isSelected ? "text-text" : isDir && isExpanded ? "text-text font-medium" : "text-text-2"),
-                )}
-              >
-                {displayName}
+            >
+              {displayName}
+            </span>
+            {gitStatus && !isDir && (
+              <span className={cn("text-[10px] ml-auto shrink-0 font-mono", gitColor)}>
+                {gitStatus}
               </span>
-              {gitStatus && !isDir && (
-                <span className={cn("text-[10px] ml-auto shrink-0 font-mono", gitColor)}>
-                  {gitStatus}
-                </span>
-              )}
-            </button>
-          </ContextMenuTrigger>
-          <TreeNodeContextMenu
-            node={node}
-            isDir={isDir}
-            projectName={projectName}
-            selectedFiles={selectedFiles}
-            compareSelection={compareSelection}
-            clipboard={clipboard}
-            onAction={onAction}
-          />
-        </ContextMenu>
-      )}
-
-      {isDir && isExpanded && isCreatingHere && (
-        <InlineTreeInput
-          defaultValue=""
-          placeholder={inlineAction!.type === "new-file" ? "filename.ts" : "folder-name"}
-          depth={depth + 1}
-          icon={inlineAction!.type === "new-file" ? "file" : "folder"}
-          onConfirm={async (name) => {
-            const type = inlineAction!.type === "new-file" ? "file" : "directory";
-            const targetPath = effectiveNode.path || node.path;
-            const fullPath = targetPath ? `${targetPath}/${name}` : name;
-            await api.post(`${projectUrl(projectName)}/files/create`, { path: fullPath, type });
-            clearInlineAction();
-            const store = useFileStore.getState();
-            store.invalidateIndex();
-            store.loadIndex(projectName);
-            store.invalidateFolder(projectName, targetPath);
-          }}
-          onCancel={clearInlineAction}
-        />
-      )}
-
-      {isDir && isExpanded && sortedChildren.map((child) => (
-        <TreeNode
-          key={child.path}
-          node={child}
-          depth={depth + 1}
+            )}
+          </button>
+        </ContextMenuTrigger>
+        <TreeNodeContextMenu
+          node={node}
+          isDir={isDir}
           projectName={projectName}
+          selectedFiles={selectedFiles}
+          compareSelection={compareSelection}
+          clipboard={clipboard}
           onAction={onAction}
-          onFileDrop={onFileDrop}
-          onFileOpen={onFileOpen}
         />
-      ))}
+      </ContextMenu>
     </div>
   );
 });

package/src/web/components/explorer/use-tree-keyboard-nav.ts

@@ -3,7 +3,8 @@
  * Arrow keys, Enter, F2, Delete on focused tree items.
  */
 import { useMemo, type KeyboardEvent } from "react";
-import { useFileStore, type FileNode } from "@/stores/file-store";
+import { type FileNode } from "@/stores/file-store";
+import { visibleNodesOf } from "./flatten-visible-tree";
 
 interface UseTreeKeyboardNavOptions {
   tree: FileNode[];
@@ -27,35 +28,7 @@ export function useTreeKeyboardNav({
   onAction,
 }: UseTreeKeyboardNavOptions) {
   /** Flat list of visible nodes (respects expand state and compact folders) */
-  const visibleNodes = useMemo(() => {
-    const result: FileNode[] = [];
-    function walk(nodes: FileNode[]) {
-      const sorted = [...nodes].sort((a, b) => {
-        if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
-        return a.name.localeCompare(b.name);
-      });
-      for (const n of sorted) {
-        // Skip compacted intermediate dirs (single-child chains rendered as one row)
-        let effective = n;
-        if (n.type === "directory" && expandedPaths.has(n.path) && n.children) {
-          while (
-            effective.children &&
-            effective.children.length === 1 &&
-            effective.children[0]!.type === "directory" &&
-            expandedPaths.has(effective.children[0]!.path)
-          ) {
-            effective = effective.children[0]!;
-          }
-        }
-        result.push(effective);
-        if (effective.type === "directory" && expandedPaths.has(effective.path) && effective.children) {
-          walk(effective.children);
-        }
-      }
-    }
-    walk(tree);
-    return result;
-  }, [tree, expandedPaths]);
+  const visibleNodes = useMemo(() => visibleNodesOf(tree, expandedPaths), [tree, expandedPaths]);
 
   const focusedNode = useMemo(
     () => visibleNodes.find((n) => n.path === focusedPath) ?? null,

package/src/web/stores/file-store.ts

@@ -2,6 +2,8 @@ import { create } from "zustand";
 import { api, projectUrl } from "@/lib/api-client";
 import type { FileEntry, FileDirEntry } from "../../types/project";
 import { entriesToNodes, mergeChildren } from "./file-tree-merge-helpers";
+import { schedulePrefetch, cancelPrefetch } from "./file-tree-prefetch";
+import { visibleNodesOf } from "@/components/explorer/flatten-visible-tree";
 
 export type { FileEntry };
 
@@ -51,7 +53,9 @@ interface FileStore {
   setClipboard(clipboard: ClipboardState | null): void;
   setFocusedPath(path: string | null): void;
   loadRoot(projectName: string): Promise<void>;
-  loadChildren(projectName: string, folderPath: string): Promise<void>;
+  loadChildren(projectName: string, folderPath: string, opts?: { prefetch?: boolean }): Promise<void>;
+  /** Load many folders in one request (expanded-state restore, deep expand) */
+  loadPathsBatch(projectName: string, paths: string[]): Promise<void>;
   loadIndex(projectName: string): Promise<void>;
   invalidateIndex(): void;
   invalidateFolder(projectName: string, folderPath: string): Promise<void>;
@@ -66,6 +70,30 @@ interface FileStore {
   fetchTree(projectName: string): Promise<void>;
 }
 
+/** Locate a node in the lazy tree by its project-relative path */
+function findNodeByPath(tree: FileNode[], path: string): FileNode | undefined {
+  let nodes = tree;
+  for (;;) {
+    const node = nodes.find((n) => n.path === path || path.startsWith(`${n.path}/`));
+    if (!node) return undefined;
+    if (node.path === path) return node;
+    nodes = node.children ?? [];
+  }
+}
+
+/** Enqueue idle prefetch of the given nodes' children (dirs only, skips ignored) */
+function queuePrefetchFor(
+  get: () => FileStore,
+  projectName: string,
+  children: FileNode[],
+): void {
+  schedulePrefetch(
+    children,
+    (path) => get().loadedPaths.has(path) || get().inflight.has(path),
+    (path) => get().loadChildren(projectName, path, { prefetch: true }),
+  );
+}
+
 export const useFileStore = create<FileStore>((set, get) => ({
   tree: [],
   fileIndex: [],
@@ -95,6 +123,7 @@ export const useFileStore = create<FileStore>((set, get) => ({
       const loadedPaths = new Set(get().loadedPaths);
       loadedPaths.add(""); // root is loaded
       set({ tree: rootNodes, loading: false, loadedPaths });
+      queuePrefetchFor(get, projectName, rootNodes);
     } catch (err) {
       set({
         error: err instanceof Error ? err.message : "Failed to load files",
@@ -103,11 +132,13 @@ export const useFileStore = create<FileStore>((set, get) => ({
     }
   },
 
-  loadChildren: async (projectName: string, folderPath: string) => {
+  loadChildren: async (projectName: string, folderPath: string, opts?: { prefetch?: boolean }) => {
     const state = get();
 
     // Idempotent guard — skip if already loaded
     if (state.loadedPaths.has(folderPath)) return;
+    // Prefetch never preempts an in-flight user-initiated request
+    if (opts?.prefetch && state.inflight.has(folderPath)) return;
 
     // Abort any existing in-flight request for this path
     const existing = state.inflight.get(folderPath);
@@ -136,6 +167,8 @@ export const useFileStore = create<FileStore>((set, get) => ({
       const newInflight = new Map(currentState.inflight);
       newInflight.delete(folderPath);
       set({ tree: newTree, loadedPaths: newLoadedPaths, inflight: newInflight });
+      // One level ahead only: prefetched loads don't cascade further
+      if (!opts?.prefetch) queuePrefetchFor(get, projectName, children);
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") return;
       // Remove from inflight on error
@@ -145,6 +178,44 @@ export const useFileStore = create<FileStore>((set, get) => ({
     }
   },
 
+  loadPathsBatch: async (projectName: string, paths: string[]) => {
+    const state = get();
+    const toLoad = [...new Set(paths)].filter((p) => !state.loadedPaths.has(p));
+    if (toLoad.length === 0) return;
+    if (state.tree.length === 0) set({ loading: true, error: null });
+    try {
+      const results = await api.post<{ path: string; entries?: FileDirEntry[]; error?: string }[]>(
+        `${projectUrl(projectName)}/files/list-batch`,
+        { paths: toLoad },
+      );
+      const current = get();
+      let newTree = current.tree;
+      const newLoaded = new Set(current.loadedPaths);
+      const newExpanded = new Set(current.expandedPaths);
+      // Parents before children so mergeChildren always finds its target node
+      const ordered = [...results].sort((a, b) => a.path.split("/").length - b.path.split("/").length);
+      for (const r of ordered) {
+        if (r.error != null || !r.entries) {
+          // Stale persisted path (deleted folder) — drop from expanded state
+          newExpanded.delete(r.path);
+          continue;
+        }
+        const children = entriesToNodes(r.entries, r.path);
+        newTree = r.path === "" ? children : mergeChildren(newTree, r.path, children);
+        newLoaded.add(r.path);
+      }
+      set({ tree: newTree, loadedPaths: newLoaded, expandedPaths: newExpanded, loading: false });
+      // Stay one level ahead of the restored view
+      const rootChildren = newTree;
+      queuePrefetchFor(get, projectName, rootChildren);
+    } catch (err) {
+      set({
+        error: get().tree.length === 0 ? (err instanceof Error ? err.message : "Failed to load files") : null,
+        loading: false,
+      });
+    }
+  },
+
   loadIndex: async (projectName: string) => {
     set({ indexStatus: "loading" });
     try {
@@ -190,6 +261,10 @@ export const useFileStore = create<FileStore>((set, get) => ({
       // Lazy load children if not yet loaded
       if (!state.loadedPaths.has(path)) {
         get().loadChildren(projectName, path);
+      } else {
+        // Already loaded (e.g. by prefetch) — stay one level ahead of the user
+        const node = findNodeByPath(get().tree, path);
+        if (node?.children) queuePrefetchFor(get, projectName, node.children);
       }
     }
   },
@@ -220,6 +295,7 @@ export const useFileStore = create<FileStore>((set, get) => ({
   clearSelection: () => set({ selectedFiles: [] }),
 
   reset: () => {
+    cancelPrefetch();
     // Abort all in-flight requests
     for (const ctrl of get().inflight.values()) ctrl.abort();
     set({
@@ -245,34 +321,30 @@ export const useFileStore = create<FileStore>((set, get) => ({
   },
 }));
 
+// --- Expanded-state persistence (per project, localStorage) ---
+
+const EXPANDED_KEY_PREFIX = "ppm-explorer-expanded:";
+
+export function loadPersistedExpanded(projectName: string): string[] {
+  try {
+    const raw = localStorage.getItem(EXPANDED_KEY_PREFIX + projectName);
+    const arr = raw ? JSON.parse(raw) : [];
+    return Array.isArray(arr) ? arr.filter((p): p is string => typeof p === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+export function savePersistedExpanded(projectName: string, expandedPaths: Set<string>): void {
+  try {
+    // Root ("") is always expanded — no need to persist it
+    const paths = [...expandedPaths].filter((p) => p !== "").slice(0, 50);
+    localStorage.setItem(EXPANDED_KEY_PREFIX + projectName, JSON.stringify(paths));
+  } catch { /* quota/unavailable — skip */ }
+}
+
 /** Compute flat visible path list from current tree state (for range selection) */
 export function getVisiblePaths(): string[] {
   const { tree, expandedPaths } = useFileStore.getState();
-  const result: string[] = [];
-  function walk(nodes: FileNode[]) {
-    const sorted = [...nodes].sort((a, b) => {
-      if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
-    for (const n of sorted) {
-      // Skip compacted intermediate dirs (matches compact folder rendering)
-      let effective = n;
-      if (n.type === "directory" && expandedPaths.has(n.path) && n.children) {
-        while (
-          effective.children &&
-          effective.children.length === 1 &&
-          effective.children[0]!.type === "directory" &&
-          expandedPaths.has(effective.children[0]!.path)
-        ) {
-          effective = effective.children[0]!;
-        }
-      }
-      result.push(effective.path);
-      if (effective.type === "directory" && expandedPaths.has(effective.path) && effective.children) {
-        walk(effective.children);
-      }
-    }
-  }
-  walk(tree);
-  return result;
+  return visibleNodesOf(tree, expandedPaths).map((n) => n.path);
 }

package/src/web/stores/file-tree-prefetch.ts

@@ -0,0 +1,57 @@
+/**
+ * Idle prefetch queue for explorer folder children.
+ * After a folder loads, children of its non-gitignored subfolders are fetched
+ * during browser idle time so the next click renders instantly (hides remote RTT).
+ * One level ahead only — prefetched loads never enqueue further prefetches.
+ */
+import type { FileNode } from "./file-store";
+
+const MAX_FOLDERS_PER_BATCH = 20;
+const CONCURRENCY = 3;
+
+type LoadFn = (path: string) => Promise<void>;
+
+let queue: string[] = [];
+let active = 0;
+let generation = 0;
+let loadFn: LoadFn | null = null;
+
+const idle: (cb: () => void) => void =
+  typeof requestIdleCallback === "function"
+    ? (cb) => requestIdleCallback(() => cb(), { timeout: 1000 })
+    : (cb) => setTimeout(cb, 200);
+
+function pump(gen: number): void {
+  if (gen !== generation) return;
+  while (active < CONCURRENCY && queue.length > 0) {
+    const path = queue.shift()!;
+    active++;
+    loadFn!(path).finally(() => {
+      active--;
+      if (gen === generation) idle(() => pump(gen));
+    });
+  }
+}
+
+/** Queue children of the given nodes for idle prefetch (skips ignored dirs) */
+export function schedulePrefetch(
+  children: FileNode[],
+  isAlreadyLoadedOrInflight: (path: string) => boolean,
+  load: LoadFn,
+): void {
+  loadFn = load;
+  const dirs = children
+    .filter((c) => c.type === "directory" && !c.ignored && !isAlreadyLoadedOrInflight(c.path))
+    .slice(0, MAX_FOLDERS_PER_BATCH)
+    .map((c) => c.path);
+  if (dirs.length === 0) return;
+  queue.push(...dirs.filter((p) => !queue.includes(p)));
+  const gen = generation;
+  idle(() => pump(gen));
+}
+
+/** Drop all pending prefetches (project switch / store reset) */
+export function cancelPrefetch(): void {
+  generation++;
+  queue = [];
+}