refactor: extract psysonic-syncfs crate (M4/7)

Moves all on-disk cache + device-sync code out of the top crate:

  crates/psysonic-syncfs/                      new lib crate
    src/cache/{offline,hot,downloads,fs_utils} unchanged behaviour
    src/sync/{batch,device}                    (no tray.rs — that's UI)
    src/file_transfer.rs                       shared HTTP helpers
    src/lib.rs                                 + DownloadSemaphore type
                                               + sync_cancel_flags fn

The shell crate keeps `lib_commands/sync/tray.rs` (OS tray icon — UI
concern, will move to shell-tauri at M7) but drops the rest of
`lib_commands/cache/` and the syncfs sibling files.

Tauri command quirk surfaced and resolved: `#[tauri::command]` puts its
`__cmd__*` and `__tauri_command_name_*` helper macros at the *exact*
module of the function, and `pub use` doesn't carry them across module
boundaries. invoke_handler! in lib.rs now references each syncfs
command via its full deepest path
(`psysonic_syncfs::cache::offline::download_track_offline`, etc.) so
Tauri's macros resolve at the right scope. Same approach the audio
crate already uses (`audio::commands::audio_play`).

Cross-crate ref migrations applied via batch sed:
  crate::audio::*               → psysonic_audio::*
  crate::analysis_runtime::*    → psysonic_analysis::analysis_runtime::*
  crate::analysis_cache::*      → psysonic_analysis::analysis_cache::*
  crate::subsonic_wire_user_agent → psysonic_core::user_agent::*
  super::super::file_transfer:: → crate::file_transfer::

Behaviour preserving. Cargo check + clippy --workspace clean.

src-tauri/crates/psysonic-syncfs/src/cache/downloads.rs

@@ -0,0 +1,404 @@
+use tauri::{Emitter, Manager};
+
+use psysonic_core::user_agent::subsonic_wire_user_agent;
+
+pub fn resolve_hot_cache_root(
+    custom_dir: Option<String>,
+    app: &tauri::AppHandle,
+) -> Result<std::path::PathBuf, String> {
+    if let Some(ref cd) = custom_dir.filter(|s| !s.is_empty()) {
+        let base = std::path::PathBuf::from(cd);
+        if !base.exists() {
+            return Err("VOLUME_NOT_FOUND".to_string());
+        }
+        Ok(base.join("psysonic-hot-cache"))
+    } else {
+        Ok(app
+            .path()
+            .app_data_dir()
+            .map_err(|e| e.to_string())?
+            .join("psysonic-hot-cache"))
+    }
+}
+
+/// Returns true if the current Linux system is Arch-based
+/// (checks /etc/arch-release and /etc/os-release).
+#[tauri::command]
+pub fn check_arch_linux() -> bool {
+    #[cfg(target_os = "linux")]
+    {
+        if std::path::Path::new("/etc/arch-release").exists() {
+            return true;
+        }
+        if let Ok(content) = std::fs::read_to_string("/etc/os-release") {
+            for line in content.lines() {
+                let lower = line.to_lowercase();
+                if lower.starts_with("id=arch") { return true; }
+                if lower.starts_with("id_like=") && lower.contains("arch") { return true; }
+            }
+        }
+        false
+    }
+    #[cfg(not(target_os = "linux"))]
+    { false }
+}
+
+/// Progress payload emitted during an update binary download.
+#[derive(Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct UpdateDownloadProgress {
+    bytes: u64,
+    total: Option<u64>,
+}
+
+/// Downloads an update installer/package to the user's Downloads folder.
+/// Emits `update:download:progress` events with `{ bytes, total }` every 250 ms.
+/// Returns the final absolute file path on success.
+#[tauri::command]
+pub async fn download_update(url: String, filename: String, app: tauri::AppHandle) -> Result<String, String> {
+    use futures_util::StreamExt;
+    use std::time::{Duration, Instant};
+    use tokio::io::AsyncWriteExt;
+
+    const EMIT_INTERVAL: Duration = Duration::from_millis(250);
+
+    let dest_dir = app.path().download_dir().map_err(|e| e.to_string())?;
+    let dest_path = dest_dir.join(&filename);
+    let part_path = dest_dir.join(format!("{}.part", filename));
+
+    let client = reqwest::Client::builder()
+        .user_agent(subsonic_wire_user_agent())
+        .connect_timeout(Duration::from_secs(30))
+        .timeout(Duration::from_secs(3600))
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let response = client.get(&url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("HTTP {}", response.status().as_u16()));
+    }
+
+    let total = response.content_length();
+
+    let result: Result<u64, String> = async {
+        let mut file = tokio::fs::File::create(&part_path)
+            .await
+            .map_err(|e| e.to_string())?;
+
+        let mut bytes_done: u64 = 0;
+        let mut stream = response.bytes_stream();
+        let mut last_emit = Instant::now();
+
+        while let Some(chunk) = stream.next().await {
+            let chunk = chunk.map_err(|e| e.to_string())?;
+            file.write_all(&chunk).await.map_err(|e| e.to_string())?;
+            bytes_done += chunk.len() as u64;
+
+            if last_emit.elapsed() >= EMIT_INTERVAL {
+                let _ = app.emit("update:download:progress", UpdateDownloadProgress {
+                    bytes: bytes_done,
+                    total,
+                });
+                last_emit = Instant::now();
+            }
+        }
+        file.flush().await.map_err(|e| e.to_string())?;
+        Ok(bytes_done)
+    }.await;
+
+    match result {
+        Err(e) => {
+            let _ = tokio::fs::remove_file(&part_path).await;
+            Err(e)
+        }
+        Ok(bytes_done) => {
+            let _ = app.emit("update:download:progress", UpdateDownloadProgress {
+                bytes: bytes_done,
+                total: Some(bytes_done),
+            });
+            tokio::fs::rename(&part_path, &dest_path)
+                .await
+                .map_err(|e| e.to_string())?;
+            Ok(dest_path.to_string_lossy().into_owned())
+        }
+    }
+}
+
+/// Fetches synced lyrics from Netease Cloud Music for a given artist + title.
+/// Performs a track search, then fetches the LRC string for the best match.
+/// Returns `None` if no match or no lyrics are found.
+#[tauri::command]
+pub async fn fetch_netease_lyrics(artist: String, title: String) -> Result<Option<String>, String> {
+    let client = reqwest::Client::builder()
+        .user_agent(subsonic_wire_user_agent())
+        .timeout(std::time::Duration::from_secs(8))
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let query = format!("{} {}", artist, title);
+    let params = [("s", query.as_str()), ("type", "1"), ("limit", "5")];
+    let search: serde_json::Value = client
+        .post("https://music.163.com/api/search/get")
+        .header("Referer", "https://music.163.com")
+        .form(&params)
+        .send()
+        .await
+        .map_err(|e| e.to_string())?
+        .json()
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let song_id = match search["result"]["songs"][0]["id"].as_i64() {
+        Some(id) => id,
+        None => return Ok(None),
+    };
+
+    let lyrics: serde_json::Value = client
+        .get(format!(
+            "https://music.163.com/api/song/lyric?id={}&lv=1&kv=1&tv=-1",
+            song_id
+        ))
+        .header("Referer", "https://music.163.com")
+        .send()
+        .await
+        .map_err(|e| e.to_string())?
+        .json()
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let lrc = lyrics["lrc"]["lyric"].as_str().unwrap_or("").trim().to_string();
+    Ok(if lrc.is_empty() { None } else { Some(lrc) })
+}
+
+/// Reads embedded synced / unsynced lyrics from a local audio file.
+///
+/// Priority order:
+///   MP3  → ID3v2 SYLT (synchronized, ms timestamps) → ID3v2 USLT (plain)
+///   FLAC → Vorbis SYNCEDLYRICS (LRC string)          → Vorbis LYRICS (plain)
+///
+/// Returns a standard LRC string (`[mm:ss.cc]line\n…`) for synced lyrics,
+/// or plain text for unsynced lyrics.  Returns `None` when no lyrics are found.
+/// Errors are silenced and mapped to `None` so the frontend falls through to the
+/// next lyrics source without crashing.
+#[tauri::command]
+pub fn get_embedded_lyrics(path: String) -> Option<String> {
+    use lofty::file::FileType;
+    use lofty::prelude::*;
+    use lofty::probe::Probe;
+
+    let fpath = std::path::Path::new(&path);
+    if !fpath.exists() {
+        return None;
+    }
+
+    // Detect file type from magic bytes only — no full tag read yet.
+    // guess_file_type() consumes self and returns Self, so reassign.
+    let probe = Probe::open(fpath).ok()?;
+    let probe = probe.guess_file_type().ok()?;
+    let file_type = probe.file_type();
+
+    // ── MP3 / MPEG: use the `id3` crate for SYLT / USLT ─────────────────────
+    // lofty's MpegFile::id3v2_tag field is pub — not accessible here.
+    // The `id3` crate exposes a clean public API for typed ID3v2 frames.
+    if matches!(file_type, Some(FileType::Mpeg)) {
+        use id3::{Content, Tag as Id3Tag};
+
+        if let Ok(tag) = Id3Tag::read_from_path(fpath) {
+            // 1. SYLT — millisecond-timestamped synced lyrics.
+            for frame in tag.frames() {
+                if frame.id() != "SYLT" {
+                    continue;
+                }
+                if let Content::SynchronisedLyrics(sylt) = frame.content() {
+                    // Only accept millisecond timestamps — MPEG-frame-based
+                    // timestamps can't be converted to wall-clock seconds.
+                    if sylt.timestamp_format != id3::frame::TimestampFormat::Ms {
+                        continue;
+                    }
+                    let lrc: String = sylt
+                        .content
+                        .iter()
+                        .filter_map(|(ms, text)| {
+                            let t = text.trim();
+                            if t.is_empty() {
+                                return None;
+                            }
+                            let mins = ms / 60_000;
+                            let secs = (ms % 60_000) / 1_000;
+                            let cs   = (ms % 1_000) / 10;
+                            // [mm:ss.cc] matches parseLrc's /\d+(?:\.\d*)?/ regex
+                            Some(format!("[{:02}:{:02}.{:02}]{}\n", mins, secs, cs, t))
+                        })
+                        .collect();
+                    if !lrc.is_empty() {
+                        return Some(lrc.trim_end().to_owned());
+                    }
+                }
+            }
+
+            // 2. USLT — unsynchronized lyrics, plain-text fallback.
+            for frame in tag.frames() {
+                if frame.id() != "USLT" {
+                    continue;
+                }
+                if let Content::Lyrics(uslt) = frame.content() {
+                    let text = uslt.text.trim();
+                    if !text.is_empty() {
+                        return Some(text.to_owned());
+                    }
+                }
+            }
+        }
+        return None; // MPEG file but no usable lyrics found
+    }
+
+    // ── FLAC / Vorbis / Opus / M4A: generic lofty tag API ────────────────────
+    // Vorbis SYNCEDLYRICS stores a complete LRC string in a plain comment field.
+    // In newer lofty versions, construct dynamic keys via ItemKey::from_key.
+    let tagged = probe.read().ok()?;
+    for tag in tagged.tags() {
+        if let Some(sync_key) = ItemKey::from_key(tag.tag_type(), "SYNCEDLYRICS") {
+            if let Some(lrc) = tag.get_string(sync_key) {
+                let lrc = lrc.trim();
+                if !lrc.is_empty() {
+                    return Some(lrc.to_owned());
+                }
+            }
+        }
+        if let Some(plain) = tag.get_string(ItemKey::Lyrics) {
+            let plain = plain.trim();
+            if !plain.is_empty() {
+                return Some(plain.to_owned());
+            }
+        }
+    }
+
+    None
+}
+
+/// Opens a directory in the OS file manager (Explorer / Finder / Nautilus).
+/// Uses platform-specific process spawning — tauri-plugin-shell's open() only
+/// allows https:// URLs per the capability scope and fails silently for paths.
+#[tauri::command]
+pub fn open_folder(path: String) -> Result<(), String> {
+    #[cfg(target_os = "windows")]
+    {
+        std::process::Command::new("explorer.exe")
+            .arg(&path)
+            .spawn()
+            .map_err(|e| e.to_string())?;
+    }
+    #[cfg(target_os = "macos")]
+    {
+        std::process::Command::new("open")
+            .arg(&path)
+            .spawn()
+            .map_err(|e| e.to_string())?;
+    }
+    #[cfg(target_os = "linux")]
+    {
+        std::process::Command::new("xdg-open")
+            .arg(&path)
+            .spawn()
+            .map_err(|e| e.to_string())?;
+    }
+    Ok(())
+}
+
+/// Progress payload emitted to the frontend during a ZIP download.
+/// `total` is `None` when the server doesn't send a `Content-Length` header
+/// (Navidrome on-the-fly ZIPs).
+#[derive(Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ZipProgress {
+    id: String,
+    bytes: u64,
+    total: Option<u64>,
+}
+
+/// Downloads a server-generated ZIP (album/playlist) directly to disk via streaming.
+/// Emits `download:zip:progress` events every 500 ms so the frontend can show
+/// live MB-counter without holding any binary data in the WebView process.
+/// Returns the final destination path on success.
+#[tauri::command]
+pub async fn download_zip(
+    id: String,
+    url: String,
+    dest_path: String,
+    app: tauri::AppHandle,
+) -> Result<String, String> {
+    use futures_util::StreamExt;
+    use std::time::{Duration, Instant};
+    use tokio::io::AsyncWriteExt;
+
+    const EMIT_INTERVAL: Duration = Duration::from_millis(500);
+
+    let client = reqwest::Client::builder()
+        .user_agent(subsonic_wire_user_agent())
+        .connect_timeout(Duration::from_secs(30))
+        .timeout(Duration::from_secs(7200)) // up to 2 h for large on-the-fly ZIPs
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let response = client.get(&url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("HTTP {}", response.status().as_u16()));
+    }
+
+    let total = response.content_length(); // None for Navidrome on-the-fly ZIPs
+    let part_path = format!("{dest_path}.part");
+
+    // Stream to .part file; rename on success, delete on error.
+    let result: Result<u64, String> = async {
+        let mut file = tokio::fs::File::create(&part_path)
+            .await
+            .map_err(|e| e.to_string())?;
+
+        let mut bytes_done: u64 = 0;
+        let mut stream = response.bytes_stream();
+        let mut last_emit = Instant::now();
+
+        while let Some(chunk) = stream.next().await {
+            let chunk = chunk.map_err(|e| e.to_string())?;
+            file.write_all(&chunk).await.map_err(|e| e.to_string())?;
+            bytes_done += chunk.len() as u64;
+
+            if last_emit.elapsed() >= EMIT_INTERVAL {
+                let _ = app.emit("download:zip:progress", ZipProgress {
+                    id: id.clone(),
+                    bytes: bytes_done,
+                    total,
+                });
+                last_emit = Instant::now();
+            }
+        }
+        file.flush().await.map_err(|e| e.to_string())?;
+        Ok(bytes_done)
+    }.await;
+
+    match result {
+        Err(e) => {
+            let _ = tokio::fs::remove_file(&part_path).await;
+            Err(e)
+        }
+        Ok(bytes_done) => {
+            // Final emission so the frontend sees 100 % (or final MB count).
+            let _ = app.emit("download:zip:progress", ZipProgress {
+                id: id.clone(),
+                bytes: bytes_done,
+                total: Some(bytes_done),
+            });
+            tokio::fs::rename(&part_path, &dest_path)
+                .await
+                .map_err(|e| e.to_string())?;
+            Ok(dest_path)
+        }
+    }
+}
+
+#[derive(serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HotCacheDownloadResult {
+    pub path: String,
+    pub size: u64,
+}

src-tauri/crates/psysonic-syncfs/src/cache/fs_utils.rs

@@ -0,0 +1,53 @@
+use std::path::Path;
+
+/// Recursively sums the size of all files under `root`.
+/// Missing roots, unreadable directories, and unreadable files are silently skipped.
+pub fn dir_size_recursive(root: &Path) -> u64 {
+    if !root.exists() {
+        return 0;
+    }
+    let mut total: u64 = 0;
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let rd = match std::fs::read_dir(&dir) {
+            Ok(r) => r,
+            Err(_) => continue,
+        };
+        for entry in rd.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                stack.push(path);
+            } else if let Ok(meta) = std::fs::metadata(&path) {
+                total += meta.len();
+            }
+        }
+    }
+    total
+}
+
+/// Walks upward from `start_dir`, removing each empty directory using `remove_dir`
+/// (never `remove_dir_all`). Stops as soon as a non-empty directory is hit, the
+/// boundary is reached, or removal fails.
+///
+/// `boundary` is never removed and is treated as a hard stop. If `start_dir` is
+/// not under `boundary`, the function is a no-op.
+pub fn prune_empty_dirs_up_to(start_dir: &Path, boundary: &Path) {
+    let mut current = Some(start_dir.to_path_buf());
+    while let Some(dir) = current {
+        if dir == boundary || !dir.starts_with(boundary) {
+            break;
+        }
+        match std::fs::read_dir(&dir) {
+            Ok(mut entries) => {
+                if entries.next().is_some() {
+                    break;
+                }
+                if std::fs::remove_dir(&dir).is_err() {
+                    break;
+                }
+                current = dir.parent().map(|p| p.to_path_buf());
+            }
+            Err(_) => break,
+        }
+    }
+}

src-tauri/crates/psysonic-syncfs/src/cache/hot.rs

@@ -0,0 +1,231 @@
+use psysonic_analysis::analysis_runtime::enqueue_analysis_seed;
+use psysonic_audio as audio;
+use psysonic_core::user_agent::subsonic_wire_user_agent;
+
+use crate::file_transfer::stream_to_file;
+use super::downloads::{resolve_hot_cache_root, HotCacheDownloadResult};
+use super::offline::enqueue_analysis_seed_from_file;
+
+#[tauri::command]
+pub async fn download_track_hot_cache(
+    track_id: String,
+    server_id: String,
+    url: String,
+    suffix: String,
+    custom_dir: Option<String>,
+    app: tauri::AppHandle,
+) -> Result<HotCacheDownloadResult, String> {
+    let root = resolve_hot_cache_root(custom_dir, &app)?;
+    let cache_dir = root.join(&server_id);
+
+    tokio::fs::create_dir_all(&cache_dir)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let file_path = cache_dir.join(format!("{}.{}", track_id, suffix));
+    let path_str = file_path.to_string_lossy().to_string();
+
+    if file_path.exists() {
+        let size = tokio::fs::metadata(&file_path)
+            .await
+            .map(|m| m.len())
+            .unwrap_or(0);
+        crate::app_deprintln!(
+            "[hot-cache] download disk_hit track_id={} server_id={} bytes={}",
+            track_id,
+            server_id,
+            size
+        );
+        // Disk hit: still seed analysis, but do not block the command (full-file read); the
+        // prefetch worker runs invokes sequentially.
+        let app_seed = app.clone();
+        let tid = track_id.clone();
+        let fp = file_path.clone();
+        tokio::spawn(async move {
+            enqueue_analysis_seed_from_file(&app_seed, &tid, &fp).await;
+        });
+        return Ok(HotCacheDownloadResult {
+            path: path_str,
+            size,
+        });
+    }
+
+    crate::app_deprintln!(
+        "[hot-cache] download http_start track_id={} server_id={}",
+        track_id,
+        server_id
+    );
+
+    let client = reqwest::Client::builder()
+        .user_agent(subsonic_wire_user_agent())
+        .timeout(std::time::Duration::from_secs(120))
+        .build()
+        .map_err(|e| e.to_string())?;
+
+    let response = client.get(&url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("HTTP {}", response.status().as_u16()));
+    }
+
+    // Stream directly to a .part file; rename on success to avoid partial files.
+    let part_path = file_path.with_extension(format!("{suffix}.part"));
+    if let Err(e) = stream_to_file(response, &part_path).await {
+        let _ = tokio::fs::remove_file(&part_path).await;
+        return Err(e);
+    }
+    tokio::fs::rename(&part_path, &file_path)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let app_seed = app.clone();
+    let tid = track_id.clone();
+    let fp = file_path.clone();
+    tokio::spawn(async move {
+        enqueue_analysis_seed_from_file(&app_seed, &tid, &fp).await;
+    });
+
+    let size = tokio::fs::metadata(&file_path)
+        .await
+        .map(|m| m.len())
+        .unwrap_or(0);
+    crate::app_deprintln!(
+        "[hot-cache] download http_done track_id={} server_id={} bytes={}",
+        track_id,
+        server_id,
+        size
+    );
+    Ok(HotCacheDownloadResult {
+        path: path_str,
+        size,
+    })
+}
+
+/// Promotes bytes captured by the manual streaming path into hot cache on disk.
+/// Returns `Ok(None)` when no completed stream cache is available for this URL.
+#[tauri::command]
+pub async fn promote_stream_cache_to_hot_cache(
+    track_id: String,
+    server_id: String,
+    url: String,
+    suffix: String,
+    custom_dir: Option<String>,
+    app: tauri::AppHandle,
+    state: tauri::State<'_, audio::AudioEngine>,
+) -> Result<Option<HotCacheDownloadResult>, String> {
+    let root = resolve_hot_cache_root(custom_dir, &app)?;
+    let cache_dir = root.join(&server_id);
+    tokio::fs::create_dir_all(&cache_dir)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let file_path = cache_dir.join(format!("{}.{}", track_id, suffix));
+    let path_str = file_path.to_string_lossy().to_string();
+
+    if file_path.exists() {
+        let size = tokio::fs::metadata(&file_path)
+            .await
+            .map(|m| m.len())
+            .unwrap_or(0);
+        crate::app_deprintln!(
+            "[hot-cache] promote disk_hit track_id={} server_id={} bytes={}",
+            track_id,
+            server_id,
+            size
+        );
+        let app_seed = app.clone();
+        let tid = track_id.clone();
+        let fp = file_path.clone();
+        tokio::spawn(async move {
+            enqueue_analysis_seed_from_file(&app_seed, &tid, &fp).await;
+        });
+        return Ok(Some(HotCacheDownloadResult { path: path_str, size }));
+    }
+
+    let bytes = match audio::take_stream_completed_for_url(&state, &url) {
+        Some(b) => b,
+        None => {
+            crate::app_deprintln!(
+                "[hot-cache] promote skip track_id={} reason=no_completed_stream_for_url",
+                track_id
+            );
+            return Ok(None);
+        }
+    };
+
+    let part_path = file_path.with_extension(format!("{suffix}.part"));
+    if let Err(e) = tokio::fs::write(&part_path, &bytes).await {
+        let _ = tokio::fs::remove_file(&part_path).await;
+        return Err(e.to_string());
+    }
+    tokio::fs::rename(&part_path, &file_path)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let _ = enqueue_analysis_seed(&app, &track_id, &bytes).await;
+
+    let size = tokio::fs::metadata(&file_path)
+        .await
+        .map(|m| m.len())
+        .unwrap_or(0);
+    crate::app_deprintln!(
+        "[hot-cache] promote from_stream track_id={} server_id={} bytes={}",
+        track_id,
+        server_id,
+        size
+    );
+    Ok(Some(HotCacheDownloadResult { path: path_str, size }))
+}
+
+#[tauri::command]
+pub async fn get_hot_cache_size(custom_dir: Option<String>, app: tauri::AppHandle) -> u64 {
+    resolve_hot_cache_root(custom_dir, &app)
+        .map(|root| super::fs_utils::dir_size_recursive(&root))
+        .unwrap_or(0)
+}
+
+#[tauri::command]
+pub async fn delete_hot_cache_track(
+    local_path: String,
+    custom_dir: Option<String>,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let file_path = std::path::PathBuf::from(&local_path);
+    let existed = file_path.exists();
+    if existed {
+        tokio::fs::remove_file(&file_path)
+            .await
+            .map_err(|e| e.to_string())?;
+    }
+    crate::app_deprintln!(
+        "[hot-cache] delete file existed={} path_suffix={}",
+        existed,
+        file_path
+            .file_name()
+            .and_then(|s| s.to_str())
+            .unwrap_or("?")
+    );
+
+    let boundary = resolve_hot_cache_root(custom_dir, &app)?;
+    if let Some(parent) = file_path.parent() {
+        super::fs_utils::prune_empty_dirs_up_to(parent, &boundary);
+    }
+
+    Ok(())
+}
+
+/// Removes the entire hot cache root (`psysonic-hot-cache` for the active location).
+#[tauri::command]
+pub async fn purge_hot_cache(custom_dir: Option<String>, app: tauri::AppHandle) -> Result<(), String> {
+    let root = resolve_hot_cache_root(custom_dir, &app)?;
+    if !root.exists() {
+        return Ok(());
+    }
+    tokio::fs::remove_dir_all(&root)
+        .await
+        .map_err(|e| e.to_string())?;
+    crate::app_deprintln!(
+        "[hot-cache] purge root={} status=ok",
+        root.to_string_lossy()
+    );
+    Ok(())
+}

src-tauri/crates/psysonic-syncfs/src/cache/mod.rs

@@ -0,0 +1,4 @@
+mod fs_utils;
+pub mod offline;
+pub mod downloads;
+pub mod hot;

src-tauri/crates/psysonic-syncfs/src/cache/offline.rs

@@ -0,0 +1,142 @@
+use tauri::Manager;
+
+use psysonic_analysis::analysis_cache;
+use psysonic_analysis::analysis_runtime::enqueue_analysis_seed;
+use crate::DownloadSemaphore;
+
+use crate::file_transfer::{finalize_streamed_download, subsonic_http_client};
+
+// ─── Offline Track Cache ──────────────────────────────────────────────────────
+
+pub async fn enqueue_analysis_seed_from_file(
+    app: &tauri::AppHandle,
+    track_id: &str,
+    file_path: &std::path::Path,
+) {
+    if let Some(cache) = app.try_state::<analysis_cache::AnalysisCache>() {
+        if cache.cpu_seed_redundant_for_track(track_id).unwrap_or(false) {
+            return;
+        }
+    }
+    let bytes = match tokio::fs::read(file_path).await {
+        Ok(v) => v,
+        Err(_) => return,
+    };
+    if bytes.is_empty() {
+        return;
+    }
+    let _ = enqueue_analysis_seed(app, track_id, &bytes).await;
+}
+
+/// Downloads a single track to the app's offline cache directory.
+/// Returns the absolute file path so TypeScript can store it and later
+/// construct a `psysonic-local://<path>` URL for the audio engine.
+#[tauri::command]
+pub async fn download_track_offline(
+    track_id: String,
+    server_id: String,
+    url: String,
+    suffix: String,
+    custom_dir: Option<String>,
+    dl_sem: tauri::State<'_, DownloadSemaphore>,
+    app: tauri::AppHandle,
+) -> Result<String, String> {
+    // Determine base cache directory.
+    let cache_dir = if let Some(ref cd) = custom_dir {
+        let base = std::path::PathBuf::from(cd);
+        // Check that the volume/directory is still accessible.
+        if !base.exists() {
+            return Err("VOLUME_NOT_FOUND".to_string());
+        }
+        base.join(&server_id)
+    } else {
+        app.path()
+            .app_data_dir()
+            .map_err(|e| e.to_string())?
+            .join("psysonic-offline")
+            .join(&server_id)
+    };
+
+    tokio::fs::create_dir_all(&cache_dir)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let file_path = cache_dir.join(format!("{}.{}", track_id, suffix));
+    let path_str = file_path.to_string_lossy().to_string();
+
+    // Already cached — skip re-download (no semaphore needed).
+    if file_path.exists() {
+        return Ok(path_str);
+    }
+
+    // Acquire a download slot. The permit is held for the duration of the HTTP transfer
+    // and released automatically when this function returns (success or error).
+    let _permit = dl_sem.acquire().await.map_err(|e| e.to_string())?;
+
+    let client = subsonic_http_client(std::time::Duration::from_secs(120))?;
+
+    let response = client.get(&url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("HTTP {}", response.status().as_u16()));
+    }
+
+    let part_path = file_path.with_extension(format!("{suffix}.part"));
+    finalize_streamed_download(response, &file_path, &part_path).await?;
+
+    enqueue_analysis_seed_from_file(&app, &track_id, &file_path).await;
+
+    Ok(path_str)
+}
+
+/// Returns the total size in bytes of all files in the offline cache directory (and optional custom dir).
+#[tauri::command]
+pub async fn get_offline_cache_size(custom_dir: Option<String>, app: tauri::AppHandle) -> u64 {
+    let default_dir = match app.path().app_data_dir() {
+        Ok(d) => d.join("psysonic-offline"),
+        Err(_) => return 0,
+    };
+    let mut total = super::fs_utils::dir_size_recursive(&default_dir);
+
+    if let Some(cd) = custom_dir {
+        let custom = std::path::PathBuf::from(cd);
+        if custom != std::path::PathBuf::from("") {
+            total += super::fs_utils::dir_size_recursive(&custom);
+        }
+    }
+    total
+}
+
+/// Removes a cached track from the offline cache. Accepts the full local path
+/// (stored in OfflineTrackMeta) so it works regardless of which directory was used.
+/// After deleting the file, empty parent directories up to (but not including)
+/// `base_dir` are pruned using `remove_dir` (never `remove_dir_all`).
+#[tauri::command]
+pub async fn delete_offline_track(
+    local_path: String,
+    base_dir: Option<String>,
+    app: tauri::AppHandle,
+) -> Result<(), String> {
+    let file_path = std::path::PathBuf::from(&local_path);
+    if file_path.exists() {
+        tokio::fs::remove_file(&file_path)
+            .await
+            .map_err(|e| e.to_string())?;
+    }
+
+    // Determine the safe boundary — never delete at or above this directory.
+    let boundary = if let Some(bd) = base_dir.filter(|s| !s.is_empty()) {
+        std::path::PathBuf::from(bd)
+    } else {
+        app.path()
+            .app_data_dir()
+            .map_err(|e| e.to_string())?
+            .join("psysonic-offline")
+    };
+
+    if let Some(parent) = file_path.parent() {
+        super::fs_utils::prune_empty_dirs_up_to(parent, &boundary);
+    }
+
+    Ok(())
+}
+