perf: add preview image cache for screenshots

Disclosure: I developed this code utilizing LSPs and LLMs. All changes have been manually reviewed by me.

Author: FreddyFunk

src/main.rs

@@ -73,13 +73,15 @@ mod priority;
 
 mod stats;
 
+mod preview_cache;
+
 use explore::ExplorePage;
 mod explore;
 
 use nav::{Category, CategoryIndex, NavPage, ScrollContext};
 mod nav;
 
-use search::{CachedExploreResults, SearchResult};
+use search::{CachedExploreResults, GridMetrics, SearchResult};
 mod search;
 
 mod view;
@@ -305,6 +307,7 @@ pub enum Message {
     OpenDesktopId(String),
     Operation(OperationKind, BackendName, AppId, Arc<AppInfo>),
     PeriodicUpdateCheck,
+    PreviewTick,
     PendingComplete(u64),
     PendingDismiss,
     PendingError(u64, String),
@@ -1089,6 +1092,7 @@ impl App {
             backend_name,
             info.source_id
         );
+
         let sources = self.selected_sources(backend_name, &id, &info);
         let addons = self.selected_addons(backend_name, &id, &info);
         self.selected_opt = Some(Selected {
@@ -1132,6 +1136,81 @@ impl App {
         )
     }
 
+    /// Queue preview images for first N items
+    fn queue_previews(results: &[SearchResult], count: usize) {
+        for result in results.iter().take(count) {
+            if let Some(screenshot) = result.info.screenshots.first() {
+                preview_cache::queue(&screenshot.url);
+            }
+        }
+    }
+
+    /// Calculate max results per explore section based on grid columns
+    fn explore_section_max_results(cols: usize) -> usize {
+        match cols {
+            1 => 4,
+            2 => 8,
+            3 => 9,
+            _ => cols * 2,
+        }
+    }
+
+    /// Calculate grid width from window size
+    fn grid_width(&self, spacing: &cosmic_theme::Spacing) -> usize {
+        self.size
+            .get()
+            .map(|s| (s.width - 2.0 * spacing.space_s as f32).floor().max(0.0) as usize)
+            .unwrap_or(800)
+    }
+
+    /// Queue preview images for explore page sections
+    fn queue_explore_previews(&self) {
+        let spacing = theme::active().cosmic().spacing;
+        let GridMetrics { cols, .. } =
+            SearchResult::grid_metrics(&spacing, self.grid_width(&spacing));
+
+        for results in self.explore_results.values() {
+            Self::queue_previews(results, Self::explore_section_max_results(cols));
+        }
+    }
+
+    /// Queue preview images for items visible in the scroll viewport
+    fn queue_visible_previews(&self, viewport: Option<&scrollable::Viewport>) {
+        let Some(results) = self.current_results() else {
+            return;
+        };
+
+        let spacing = theme::active().cosmic().spacing;
+        let GridMetrics { cols, .. } =
+            SearchResult::grid_metrics(&spacing, self.grid_width(&spacing));
+        let row_height = SearchResult::card_height(&spacing) + spacing.space_xxs as f32;
+
+        let (first_item, count) = match viewport {
+            Some(vp) => {
+                let first_row = (vp.absolute_offset().y / row_height).floor() as usize;
+                let visible_rows = (vp.bounds().height / row_height).ceil() as usize + 2;
+                (first_row * cols, visible_rows * cols)
+            }
+            None => (0, cols * 4), // Initial load: first ~4 rows
+        };
+
+        Self::queue_previews(&results[first_item.min(results.len())..], count);
+    }
+
+    /// Get the current results being displayed based on app state
+    fn current_results(&self) -> Option<&[SearchResult]> {
+        match (
+            &self.search_results,
+            self.explore_page_opt,
+            &self.category_results,
+        ) {
+            (Some((_, r)), _, _) => Some(r),
+            (None, Some(page), _) => self.explore_results.get(&page).map(|r| r.as_slice()),
+            (None, None, Some((_, r))) => Some(r),
+            _ => None,
+        }
+    }
+
     fn update_backends(&mut self, refresh: bool) -> Task<Message> {
         let locale = self.locale.clone();
         Task::perform(
@@ -2082,6 +2161,8 @@ impl Application for App {
         let cache_start = Instant::now();
         if let Some(cached) = CachedExploreResults::load() {
             app.explore_results = cached.to_results();
+            // Queue preview images for all explore sections
+            app.queue_explore_previews();
             log::info!(
                 "explore page loaded from cache: {} categories in {:?}",
                 app.explore_results.len(),
@@ -2102,7 +2183,19 @@ impl Application for App {
             }
         }
 
-        let command = Task::batch([app.update_title(), app.update_backends(true)]);
+        let command = Task::batch([
+            app.update_title(),
+            app.update_backends(true),
+            // Run one-time preview cache cleanup in background
+            Task::perform(
+                async {
+                    tokio::task::spawn_blocking(preview_cache::enforce_size_limit)
+                        .await
+                        .ok();
+                },
+                |()| action::none(),
+            ),
+        ]);
         (app, command)
     }
 
@@ -2653,6 +2746,12 @@ impl Application for App {
                 .push(cosmic::iced::time::every(duration).map(|_| Message::PeriodicUpdateCheck));
         }
 
+        // Periodically queue preview images for visible items (catches scrollbar drag, etc.)
+        subscriptions.push(
+            cosmic::iced::time::every(std::time::Duration::from_millis(250))
+                .map(|_| Message::PreviewTick),
+        );
+
         if !self.pending_operations.is_empty() {
             #[cfg(feature = "logind")]
             {
@@ -2778,21 +2877,26 @@ impl Application for App {
                 subscriptions.push(Subscription::run_with_id(
                     url.clone(),
                     stream::channel(16, move |mut msg_tx| async move {
-                        log::info!("fetch screenshot {}", url);
+                        // Check cache first
+                        if let Some(data) = preview_cache::get_cached(&url) {
+                            log::debug!("screenshot cache hit: {}", url);
+                            let _ = msg_tx
+                                .send(Message::SelectedScreenshot(screenshot_i, url, data))
+                                .await;
+                            return pending().await;
+                        }
+
+                        log::debug!("screenshot fetch: {}", url);
                         match reqwest::get(&url).await {
                             Ok(response) => match response.bytes().await {
                                 Ok(bytes) => {
-                                    log::info!(
-                                        "fetched screenshot from {}: {} bytes",
-                                        url,
-                                        bytes.len()
-                                    );
+                                    let data = bytes.to_vec();
+                                    // Save to cache
+                                    if let Err(e) = preview_cache::save_to_cache(&url, &data) {
+                                        log::warn!("failed to cache screenshot {}: {}", url, e);
+                                    }
                                     let _ = msg_tx
-                                        .send(Message::SelectedScreenshot(
-                                            screenshot_i,
-                                            url,
-                                            bytes.to_vec(),
-                                        ))
+                                        .send(Message::SelectedScreenshot(screenshot_i, url, data))
                                         .await;
                                 }
                                 Err(err) => {
@@ -2809,6 +2913,32 @@ impl Application for App {
             }
         }
 
+        // Background preview cache downloader - wakes on notification, processes LIFO queue
+        subscriptions.push(Subscription::run_with_id(
+            "preview-cache-downloader",
+            stream::channel(1, |_| async {
+                const SIZE_LIMIT_INTERVAL: u64 = 10 * 1024 * 1024; // 10 MB
+                let mut bytes_since_limit_check: u64 = 0;
+                loop {
+                    preview_cache::wait_for_work().await;
+                    let urls = preview_cache::take_pending();
+                    for url in &urls {
+                        log::debug!("preview fetch: {}", url);
+                        if let Ok(resp) = reqwest::get(url).await {
+                            if let Ok(bytes) = resp.bytes().await {
+                                bytes_since_limit_check += bytes.len() as u64;
+                                let _ = preview_cache::save_to_cache(url, &bytes);
+                            }
+                        }
+                    }
+                    if bytes_since_limit_check >= SIZE_LIMIT_INTERVAL {
+                        preview_cache::enforce_size_limit();
+                        bytes_since_limit_check = 0;
+                    }
+                }
+            }),
+        ));
+
         Subscription::batch(subscriptions)
     }
 }

src/preview_cache.rs

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: GPL-3.0-only
+
+use std::{
+    hash::{DefaultHasher, Hash, Hasher},
+    path::PathBuf,
+    sync::{Mutex, OnceLock},
+    time::SystemTime,
+};
+use tokio::sync::Notify;
+
+/// Maximum number of URLs to take from queue per tick
+const MAX_BATCH_SIZE: usize = 5;
+
+/// Maximum cache size in bytes (250 MB)
+const MAX_CACHE_BYTES: u64 = 250 * 1024 * 1024;
+
+/// Convert a URL to a cache file path using a hash
+fn url_to_path(url: &str) -> Option<PathBuf> {
+    let mut hasher = DefaultHasher::new();
+    url.hash(&mut hasher);
+    let hash = format!("{:016x}", hasher.finish());
+    dirs::cache_dir().map(|dir| dir.join("cosmic-store/previews").join(&hash))
+}
+
+/// Get cached image data from disk (returns None if not cached)
+pub fn get_cached(url: &str) -> Option<Vec<u8>> {
+    let path = url_to_path(url)?;
+    std::fs::read(&path).ok()
+}
+
+/// Save data to disk cache
+pub fn save_to_cache(url: &str, data: &[u8]) -> std::io::Result<()> {
+    let path = url_to_path(url)
+        .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "no cache directory"))?;
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    std::fs::write(path, data)
+}
+
+/// Global download queue (LIFO for prioritizing recently viewed items)
+static PENDING: Mutex<Vec<String>> = Mutex::new(Vec::new());
+
+/// Notification for waking the background downloader
+static NOTIFY: OnceLock<Notify> = OnceLock::new();
+
+fn notify() -> &'static Notify {
+    NOTIFY.get_or_init(Notify::new)
+}
+
+/// Queue a URL for background download if not already cached
+pub fn queue(url: &str) {
+    // Skip if already cached
+    if url_to_path(url).is_some_and(|p| p.exists()) {
+        return;
+    }
+    if let Ok(mut queue) = PENDING.lock() {
+        // Avoid duplicates (cheap linear scan since queue stays small)
+        if !queue.iter().any(|u| u == url) {
+            queue.push(url.to_string());
+            notify().notify_one();
+        }
+    }
+}
+
+/// Take URLs to download (LIFO order, up to MAX_BATCH_SIZE)
+pub fn take_pending() -> Vec<String> {
+    let Ok(mut queue) = PENDING.lock() else {
+        return Vec::new();
+    };
+    let start = queue.len().saturating_sub(MAX_BATCH_SIZE);
+    queue.split_off(start)
+}
+
+/// Wait for work to be queued. Returns immediately if work is already pending.
+pub async fn wait_for_work() {
+    // Check if there's already work pending
+    if PENDING.lock().map(|q| !q.is_empty()).unwrap_or(false) {
+        return;
+    }
+    notify().notified().await;
+}
+
+/// Evict least-recently-accessed entries until total cache size is within the limit.
+pub fn enforce_size_limit() {
+    let Some(cache_dir) = dirs::cache_dir().map(|d| d.join("cosmic-store/previews")) else {
+        return;
+    };
+    let Ok(entries) = std::fs::read_dir(&cache_dir) else {
+        return;
+    };
+
+    // Collect all files with their size and access time
+    let mut files: Vec<(PathBuf, u64, SystemTime)> = Vec::new();
+    let mut total_size: u64 = 0;
+
+    for entry in entries.filter_map(Result::ok) {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+        let Ok(metadata) = path.metadata() else {
+            continue;
+        };
+        let size = metadata.len();
+        let accessed = metadata.accessed().unwrap_or(
+            metadata.modified().unwrap_or(SystemTime::UNIX_EPOCH),
+        );
+        total_size += size;
+        files.push((path, size, accessed));
+    }
+
+    if total_size <= MAX_CACHE_BYTES {
+        return;
+    }
+
+    // Sort by access time ascending (oldest accessed first)
+    files.sort_by_key(|(_, _, accessed)| *accessed);
+
+    let mut evicted = 0usize;
+    for (path, size, _) in &files {
+        if total_size <= MAX_CACHE_BYTES {
+            break;
+        }
+        if std::fs::remove_file(path).is_ok() {
+            total_size -= size;
+            evicted += 1;
+        }
+    }
+    if evicted > 0 {
+        log::info!(
+            "preview cache: evicted {} files to stay within {} MB limit",
+            evicted,
+            MAX_CACHE_BYTES / (1024 * 1024)
+        );
+    }
+}

src/search.rs

@@ -231,6 +231,11 @@ impl SearchResult {
         GridMetrics::new(width, 240 + 2 * spacing.space_s as usize, spacing.space_xxs)
     }
 
+    /// Card height including padding
+    pub fn card_height(spacing: &cosmic_theme::Spacing) -> f32 {
+        48.0 + (spacing.space_xxs as f32) * 2.0
+    }
+
     pub fn grid_view<'a, F: Fn(usize) -> Message + 'a>(
         results: &'a [Self],
         spacing: cosmic_theme::Spacing,
@@ -291,7 +296,7 @@ impl SearchResult {
         )
         .align_y(Alignment::Center)
         .width(Length::Fixed(width as f32))
-        .height(Length::Fixed(48.0 + (spacing.space_xxs as f32) * 2.0))
+        .height(Length::Fixed(Self::card_height(spacing)))
         .padding([spacing.space_xxs, spacing.space_s])
         .class(theme::Container::Card)
         .into()