Icons: Real system-folder icons (Downloads, etc.)

Phase 1 / Tier B of per-folder icons: special system folders now show their real macOS icon instead of the generic folder glyph.

- New `icons::special_folders`: classifies a folder by its well-known canonical path (resolved once via `dirs`) into a bounded `special:{name}` key. The set: home, Downloads, Desktop, Documents, Movies, Music, Pictures, Public, plus macOS-only Applications and Trash. Detection is a lexical-path `HashMap` lookup with no disk I/O (no `canonicalize` — would block on a dead mount) and no NSWorkspace/TCC, so it's safe per entry.
- `get_icon_id` now takes the entry's full `path` and routes real special folders to `special:{name}`; detection is by path, not name, so a folder merely named "Downloads" elsewhere stays `dir`. Symlinks keep `symlink-dir`.
- `icons::get_icons` fetches each uncached `special:*` from the folder's REAL path through the 8 MB-stack `fetch_path_icons` thread (the real folder can be iCloud-synced and descend into `fileproviderd`), then caches under the bounded key. FDA gate + timeout unchanged.
- `special:*` keys are bounded, so they persist to localStorage (FE) and are uncapped (Rust); cleared with the other appearance-tinted keys on theme/accent change.
- The FE prefetch path already batches visible `iconId`s through `get_icons`, and `FileIcon.svelte` falls back to `dir` while pending/gated, so no per-component wiring was needed.
- Converted `icons.rs` to `icons/mod.rs` + `icons/special_folders.rs`; added `icons/CLAUDE.md` documenting the icon-id tier scheme.
- Tests: special-folder classifier + `get_icon_id` routing (Rust), `special:` persistence + no-LRU-eviction (FE).

Author: vdavid

apps/desktop/src-tauri/src/commands/icons.rs

@@ -73,7 +73,7 @@ pub fn clear_extension_icon_cache() {
     icons::clear_extension_icon_cache();
 }
 
-/// Clears cached directory icons (`dir`, `symlink-dir`, `path:*`).
+/// Clears cached directory icons (`dir`, `symlink-dir`, `path:*`, `special:*`).
 /// Called when the system theme or accent color changes.
 #[tauri::command]
 #[specta::specta]

apps/desktop/src-tauri/src/file_system/CLAUDE.md

@@ -34,9 +34,11 @@ NSURL resource-value lookups, FileProvider queries, and similar Objective-C APIs
 system daemons. These can consume deep stack frames through FileProvider override chains (iCloud, Dropbox, etc.),
 exceeding rayon's default 2 MB worker stack. Use dedicated OS threads with an explicit stack size (8 MB) instead. This
 also prevents I/O-bound XPC calls from starving rayon's pool, which should be reserved for CPU-bound work.
-See `sync_status.rs` for the pattern. `icons.rs::fetch_path_icons` follows it too: per-folder NSWorkspace icon lookups
-on real user folders can descend into `fileproviderd` for iCloud/Dropbox folders, so the `path:`-keyed branch runs on
-8 MB threads while the extension branch (sample temp paths, never cloud) stays on rayon.
+See `sync_status.rs` for the pattern. `icons::fetch_path_icons` follows it too: per-folder NSWorkspace icon lookups on
+real user folders can descend into `fileproviderd` for iCloud/Dropbox folders, so the `path:`-keyed branch runs on 8 MB
+threads while the extension branch (sample temp paths, never cloud) stays on rayon. `special:*` (special-system-folder)
+icons fetch from the folder's REAL path too (Downloads/Desktop can be iCloud-synced), so `icons::get_icons` routes them
+through the same `fetch_path_icons` 8 MB path, not the generic per-id loop.
 
 **Never `tokio::spawn` from the notify-rs debouncer callback.** The callback runs on the notify-rs internal thread
 which has no Tokio runtime context, so `tokio::spawn` panics with "there is no reactor running". Use

apps/desktop/src-tauri/src/file_system/listing/metadata.rs

@@ -45,8 +45,20 @@ pub(crate) fn get_group_name(gid: u32) -> String {
     name
 }
 
-/// Generates icon ID based on file type and extension.
-pub(crate) fn get_icon_id(is_dir: bool, is_symlink: bool, name: &str) -> String {
+/// Generates icon ID based on file type, extension, and (for directories) the
+/// folder's well-known path.
+///
+/// `path` is the entry's full path. It's used to detect the finite set of
+/// special system folders (Downloads, Applications, the home folder, …) by
+/// canonical path — NOT by name, since any folder can be named "Downloads". A
+/// real special folder gets a bounded `special:{name}` key (Tier B); every other
+/// directory keeps the shared `dir` icon (Tier A). Detection is a cheap path
+/// comparison (no NSWorkspace, no TCC), so it's safe to run per entry.
+///
+/// Symlinks (even to a special location) keep their `symlink-dir` icon: the link
+/// badge is the salient signal, and following a symlink to classify it would
+/// cost a syscall per entry.
+pub(crate) fn get_icon_id(is_dir: bool, is_symlink: bool, name: &str, path: &str) -> String {
     if is_symlink {
         // Distinguish symlinks to directories vs files
         return if is_dir {
@@ -56,6 +68,9 @@ pub(crate) fn get_icon_id(is_dir: bool, is_symlink: bool, name: &str) -> String
         };
     }
     if is_dir {
+        if let Some(special_id) = crate::icons::special_folders::icon_id_for_path(Path::new(path)) {
+            return special_id;
+        }
         return "dir".to_string();
     }
     // Extract extension
@@ -140,7 +155,7 @@ impl FileEntry {
     /// Creates a `FileEntry` with the four essential fields set and everything else defaulted.
     pub(crate) fn new(name: String, path: String, is_dir: bool, is_symlink: bool) -> Self {
         Self {
-            icon_id: get_icon_id(is_dir, is_symlink, &name),
+            icon_id: get_icon_id(is_dir, is_symlink, &name, &path),
             name,
             path,
             is_directory: is_dir,
@@ -168,6 +183,55 @@ impl FileEntry {
     }
 }
 
+#[cfg(test)]
+mod icon_id_tests {
+    use super::*;
+
+    #[test]
+    fn plain_directory_gets_the_generic_dir_icon() {
+        let home = dirs::home_dir().expect("home_dir resolves");
+        let project = home.join("Projects").join("foo");
+        assert_eq!(get_icon_id(true, false, "foo", &project.to_string_lossy()), "dir");
+    }
+
+    #[test]
+    fn real_downloads_folder_gets_the_special_key() {
+        let downloads = dirs::download_dir().expect("download_dir resolves");
+        assert_eq!(
+            get_icon_id(true, false, "Downloads", &downloads.to_string_lossy()),
+            "special:downloads"
+        );
+    }
+
+    #[test]
+    fn a_folder_merely_named_downloads_elsewhere_stays_generic() {
+        let home = dirs::home_dir().expect("home_dir resolves");
+        let fake = home.join("Projects").join("Downloads");
+        assert_eq!(get_icon_id(true, false, "Downloads", &fake.to_string_lossy()), "dir");
+    }
+
+    #[test]
+    fn a_symlink_to_a_special_path_keeps_the_symlink_dir_icon() {
+        // Symlinks keep the link badge; we don't promote them to `special:*`.
+        let downloads = dirs::download_dir().expect("download_dir resolves");
+        assert_eq!(
+            get_icon_id(true, true, "Downloads", &downloads.to_string_lossy()),
+            "symlink-dir"
+        );
+    }
+
+    #[test]
+    fn files_are_unaffected_by_special_folder_detection() {
+        // Even a file sitting at a path that string-matches a special folder must
+        // route by extension, never to `special:*`.
+        let downloads = dirs::download_dir().expect("download_dir resolves");
+        assert_eq!(
+            get_icon_id(false, false, "notes.txt", &downloads.to_string_lossy()),
+            "ext:txt"
+        );
+    }
+}
+
 /// Extended metadata for a single file (macOS-specific fields).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]

apps/desktop/src-tauri/src/icons/CLAUDE.md

@@ -0,0 +1,50 @@
+# Icons module
+
+OS icon retrieval and caching for the file list. Entries carry only an `iconId`; the frontend batches the unique ids
+for visible rows and fetches each once via `get_icons`, so 50k files never transmit 50k icon blobs.
+
+This is the Rust `src/icons/` module. (`src-tauri/icons/`, a sibling at the crate root, holds the app *bundle* icons —
+unrelated.)
+
+## Icon-id scheme
+
+`get_icon_id` (in `file_system/listing/metadata.rs`) assigns each entry an id; `get_icons` resolves it to a base64 WebP
+data URL. The id namespace, by tier:
+
+| Tier | Id | Assigned to | Fetched from |
+| --- | --- | --- | --- |
+| A | `dir` / `symlink-dir` | every plain folder (~99%) | the home dir (sample) |
+| A | `ext:{x}` / `file` / `symlink*` | files | a per-extension temp sample / `/etc/hosts` |
+| B | `special:{name}` | the finite special **system** folders | the folder's REAL path (8 MB thread) |
+| C | `path:{dir}` / `pkg:{dir}` | per-path icons (volumes, packages, custom-icon folders) | the real path (8 MB thread) |
+| — | `git:{branch,tag,commit,fork}` | git-portal virtual entries | rendered by the FE via Lucide, never here |
+
+`dir` / `ext:*` / `file` / `symlink*` / `special:*` are inherently **bounded**, so they're uncapped and persist to
+localStorage. `path:*` / `pkg:*` are **unbounded** (grow with folders visited), so they're LRU-capped (`PATH_KEY_CAP`)
+and never persisted. See `clear_directory_icon_cache` for which keys a theme/accent change drops (`dir`, `symlink-dir`,
+`path:*`, `special:*` — all appearance-tinted by macOS).
+
+## Tier B — special system folders (`special_folders.rs`)
+
+The finite set: Downloads, Desktop, Documents, Movies, Music, Pictures, Public, the home folder, plus (macOS only)
+Applications and the Trash. Detected by **canonical path**, NOT by name — a folder merely *named* "Downloads" under
+`~/Projects/` is not the real one and stays `dir`. The set of real paths is resolved once at startup via the `dirs`
+crate (`/Applications` and `~/.Trash` are hardcoded; `dirs` has no entry for them). `classify` is a lexical-path
+`HashMap` lookup with **no disk I/O** (no `canonicalize` — it would block on a dead mount), so it's cheap enough to run
+per entry during listing.
+
+`get_icons` re-keys each uncached `special:*` id to its real path, fetches via the 8 MB `fetch_path_icons` thread (the
+real folder can be iCloud-synced and descend into `fileproviderd`; see `file_system/CLAUDE.md` § Gotchas), then caches
+under the bounded `special:{name}` key. The FE renders the fetched icon and falls back to the generic `dir` glyph while
+the fetch is pending, FDA-gated, or timed out — the feature is purely additive.
+
+Symlinks to a special location keep `symlink-dir` (the link badge is the salient signal; following the link to classify
+would cost a syscall per entry).
+
+## Threading + FDA
+
+Per-path / per-special NSWorkspace fetches run on dedicated 8 MB-stack OS threads (`fetch_path_icons`), never rayon —
+real folders can be cloud folders whose icon lookup descends through deep FileProvider XPC chains that overflow rayon's
+2 MB worker stack. The extension branch (sample temp paths, never cloud) stays on rayon. All fetches are FDA-gated in
+`commands/icons.rs` (NSWorkspace touches TCC services); the FE re-requests after the gate clears. Linux skips
+NSWorkspace entirely and resolves via the XDG theme lookup, so `special:*` degrades to the generic folder icon there.

apps/desktop/src-tauri/src/icons.rs apps/desktop/src-tauri/src/icons/mod.rsapps/desktop/src-tauri/src/icons.rs renamed to apps/desktop/src-tauri/src/icons/mod.rs

@@ -4,6 +4,8 @@
 //! Benchmarked on M1 Mac: 10 files→3.7ms, 50→8ms, 100→12.8ms, 200→21ms.
 //! Custom thread counts showed no improvement, so we use auto-detect.
 
+pub mod special_folders;
+
 use crate::config::ICON_SIZE;
 use crate::ignore_poison::RwLockIgnorePoison;
 use base64::Engine;
@@ -103,13 +105,17 @@ pub fn clear_extension_icon_cache() {
     ICON_CACHE.write_ignore_poison().retain(|key| !key.starts_with("ext:"));
 }
 
-/// Clears all cached icons for directory entries (`dir`, `symlink-dir`, `path:*`).
-/// Called when the system theme or accent color changes, since macOS folder icons
-/// are tinted by the current appearance.
+/// Clears all cached icons for directory entries (`dir`, `symlink-dir`,
+/// `path:*`, `special:*`). Called when the system theme or accent color changes,
+/// since macOS folder icons (including the special-folder glyphs) are tinted by
+/// the current appearance.
 pub fn clear_directory_icon_cache() {
-    ICON_CACHE
-        .write_ignore_poison()
-        .retain(|key| key != "dir" && key != "symlink-dir" && !key.starts_with(PATH_KEY_PREFIX));
+    ICON_CACHE.write_ignore_poison().retain(|key| {
+        key != "dir"
+            && key != "symlink-dir"
+            && !key.starts_with(PATH_KEY_PREFIX)
+            && !key.starts_with(special_folders::SPECIAL_KEY_PREFIX)
+    });
 }
 
 /// Converts an image to a base64 WebP data URL.
@@ -192,12 +198,47 @@ fn get_sample_path_for_icon_id(icon_id: &str) -> Option<PathBuf> {
 pub fn get_icons(icon_ids: Vec<String>, use_app_icons_for_documents: bool) -> HashMap<String, String> {
     let mut result = HashMap::new();
 
+    // Special system folders (`special:downloads`, …) fetch their icon from the
+    // folder's REAL path, which can be a cloud-synced location (Desktop &
+    // Documents iCloud sync) whose NSWorkspace lookup descends into
+    // `fileproviderd`. Route them through the dedicated 8 MB-stack fetch (same as
+    // the `path:` branch), NOT the generic per-id loop below, which runs on the
+    // calling thread. The result stays keyed by `special:{name}` (bounded), not
+    // by the real path.
+    let mut remaining = Vec::with_capacity(icon_ids.len());
+    let mut special_to_fetch: Vec<(String, String)> = Vec::new();
     for icon_id in icon_ids {
-        // Check cache first
         if let Some(cached) = get_cached_icon(&icon_id) {
             result.insert(icon_id, cached);
             continue;
         }
+        if icon_id.starts_with(special_folders::SPECIAL_KEY_PREFIX) {
+            if let Some(real_path) = special_folders::real_path_for_icon_id(&icon_id) {
+                special_to_fetch.push((icon_id, real_path.to_string_lossy().into_owned()));
+            }
+            // Unknown special name (no resolved standard location): skip; the
+            // frontend keeps the `dir` fallback.
+            continue;
+        }
+        remaining.push(icon_id);
+    }
+
+    if !special_to_fetch.is_empty() {
+        let paths: Vec<String> = special_to_fetch.iter().map(|(_, path)| path.clone()).collect();
+        let fetched = fetch_path_icons(paths);
+        // `fetch_path_icons` returns `(path:{real_path}, data_url)` in input
+        // order; re-key each back to its `special:{name}` id and cache under the
+        // bounded key.
+        for ((special_id, _), (_, data_url)) in special_to_fetch.into_iter().zip(fetched) {
+            if let Some(url) = data_url {
+                cache_icon(special_id.clone(), url.clone());
+                result.insert(special_id, url);
+            }
+        }
+    }
+
+    for icon_id in remaining {
+        // Cache was already checked above for this batch.
 
         // macOS: drain autoreleased ObjC objects per iteration
         // (fetch_fresh_extension_icon and fetch_icon_for_path call ObjC APIs)