Code Review: perf: optimize file tree loading performance

Overall a solid performance optimization PR with clear wins. Here is the detailed review.

👍 Highlights

1. Promise.all parallelization — Converting sequential for...of + await stat() to Promise.all(filteredEntries.map(...)) is the correct approach and the single biggest perf win.
2. Default depth 2 + lazy loading — Good trade-off. Initial load is fast; deeper content loads on demand.
3. Search debounce + batched setExpandedDirs — Replacing per-item setExpandedDirs calls inside a loop with a single batch update (collectMatches → one setExpandedDirs) eliminates N re-renders. Nice catch.
4. metadata=false skip-stat path — Skipping all stat() calls in simple view mode is a clean optimization.
5. Explicit maxDepth: 10 for full-tree consumers — Prevents regression in useFileMentions, ResearchLab, useSurveyData.

🔴 Must Fix

1. Search misses unloaded directories (medium severity)

With maxDepth: 2, files deeper than 2 levels are not in the files state until lazy-loaded. filterFiles only searches the loaded tree, so search will silently miss deeply nested files. The old behavior (depth 10) returned nearly everything, so search was complete. Now there is a silent gap.

Suggestions:

• When the search box is active, fetch with a higher maxDepth (or use a dedicated server-side search endpoint).
• At minimum, indicate this limitation in the UI (e.g., "showing results from loaded directories only").

2. View mode switch does not re-fetch metadata (medium severity)

fetchFiles passes metadata: viewMode !== 'simple'. But if the user starts in "simple" mode (no metadata) then switches to "detailed" or "compact", the file items lack size, modified, permissions. I do not see a re-fetch triggered by viewMode changes — fetchFiles appears to only run on selectedProject changes. This would cause undefined values in detailed/compact views.

Fix: either re-fetch when viewMode changes, or always include metadata and simply skip rendering it in simple mode.

🟡 Suggestions

3. children === null vs undefined convention (low severity)

The backend now sets item.children = null for not-yet-loaded directories. The frontend checks item.children === null correctly in toggleDirectory, and the render conditions (item.children && item.children.length > 0) handle null as falsy. This works, but consider making the convention explicit at the type level to avoid future confusion.

4. Unbounded parallelism in Promise.all (low severity)

For directories with thousands of entries, Promise.all fires all stat() calls simultaneously. On macOS this is usually fine (high fd limits), but on constrained environments it could hit EMFILE. Consider batching (e.g., p-limit or chunked Promise.all) if this ever becomes an issue. Not urgent.

5. Loading spinner duplication (nit)

The loading spinner block is duplicated identically across renderFileTree, renderDetailedView, and renderCompactView (3 copies). Consider extracting a small helper component.

Verdict

Approve with minor changes — Fix #1 (search accuracy) and #2 (view mode switch), the rest are nice-to-haves.