Merge pull request #974 from itkitteh/fix/socks-proxy-support

fix: support SOCKS proxies for outbound requests

locales/de.json

@@ -448,7 +448,9 @@
                 "modelName": "Modellname",
                 "fileName": "Dateiname"
             },
-            "modelNameDisplayHelp": "Wählen Sie aus, was in der Fußzeile der Modellkarte angezeigt werden soll"
+            "modelNameDisplayHelp": "Wählen Sie aus, was in der Fußzeile der Modellkarte angezeigt werden soll",
+            "cardBlurAmount": "Karten-Overlay-Unschärfe",
+            "cardBlurAmountHelp": "Passen Sie die Unschärfeintensität der Kopf- und Fußzeilen-Overlays auf Modell- und Rezeptkarten an (0 = keine Unschärfe, 20 = maximale Unschärfe)."
         },
         "folderSettings": {
             "activeLibrary": "Aktive Bibliothek",

locales/en.json

@@ -448,7 +448,9 @@
                 "modelName": "Model Name",
                 "fileName": "File Name"
             },
-            "modelNameDisplayHelp": "Choose what to display in the model card footer"
+            "modelNameDisplayHelp": "Choose what to display in the model card footer",
+            "cardBlurAmount": "Card Overlay Blur",
+            "cardBlurAmountHelp": "Adjust the blur intensity of the header and footer overlays on model and recipe cards (0 = no blur, 20 = maximum blur)."
         },
         "folderSettings": {
             "activeLibrary": "Active Library",

locales/es.json

@@ -448,7 +448,9 @@
                 "modelName": "Nombre del modelo",
                 "fileName": "Nombre del archivo"
             },
-            "modelNameDisplayHelp": "Elige qué mostrar en el pie de la tarjeta del modelo"
+            "modelNameDisplayHelp": "Elige qué mostrar en el pie de la tarjeta del modelo",
+            "cardBlurAmount": "Desenfoque de superposición de tarjetas",
+            "cardBlurAmountHelp": "Ajuste la intensidad de desenfoque de las superposiciones del encabezado y pie de página en las tarjetas de modelos y recetas (0 = sin desenfoque, 20 = desenfoque máximo)."
         },
         "folderSettings": {
             "activeLibrary": "Biblioteca activa",

locales/fr.json

@@ -448,7 +448,9 @@
                 "modelName": "Nom du modèle",
                 "fileName": "Nom du fichier"
             },
-            "modelNameDisplayHelp": "Choisissez ce qui doit être affiché dans le pied de page de la carte du modèle"
+            "modelNameDisplayHelp": "Choisissez ce qui doit être affiché dans le pied de page de la carte du modèle",
+            "cardBlurAmount": "Flou de superposition des cartes",
+            "cardBlurAmountHelp": "Ajustez l'intensité du flou des superpositions d'en-tête et de pied de page sur les cartes de modèles et de recettes (0 = aucun flou, 20 = flou maximal)."
         },
         "folderSettings": {
             "activeLibrary": "Bibliothèque active",

locales/he.json

@@ -448,7 +448,9 @@
                 "modelName": "שם מודל",
                 "fileName": "שם קובץ"
             },
-            "modelNameDisplayHelp": "בחר מה להציג בכותרת התחתונה של כרטיס המודל"
+            "modelNameDisplayHelp": "בחר מה להציג בכותרת התחתונה של כרטיס המודל",
+            "cardBlurAmount": "עוצמת טשטוש שכבת-על בכרטיס",
+            "cardBlurAmountHelp": "כוונן את עוצמת הטשטוש של שכבת-העל בכותרת ובכותרות תחתונה בכרטיסי מודל ומתכונים (0 = ללא טשטוש, 20 = טשטוש מקסימלי)."
         },
         "folderSettings": {
             "activeLibrary": "ספרייה פעילה",

locales/ja.json

@@ -448,7 +448,9 @@
                 "modelName": "モデル名",
                 "fileName": "ファイル名"
             },
-            "modelNameDisplayHelp": "モデルカードのフッターに表示する内容を選択"
+            "modelNameDisplayHelp": "モデルカードのフッターに表示する内容を選択",
+            "cardBlurAmount": "カードオーバーレイのぼかし",
+            "cardBlurAmountHelp": "モデルカードとレシピカードのヘッダー・フッターオーバーレイのぼかし強度を調整します（0 = ぼかしなし、20 = 最大ぼかし）。"
         },
         "folderSettings": {
             "activeLibrary": "アクティブライブラリ",

locales/ko.json

@@ -448,7 +448,9 @@
                 "modelName": "모델명",
                 "fileName": "파일명"
             },
-            "modelNameDisplayHelp": "모델 카드 하단에 표시할 내용을 선택하세요"
+            "modelNameDisplayHelp": "모델 카드 하단에 표시할 내용을 선택하세요",
+            "cardBlurAmount": "카드 오버레이 흐림 강도",
+            "cardBlurAmountHelp": "모델 및 레시피 카드의 헤더와 푸터 오버레이 흐림 강도를 조정합니다 (0 = 흐림 없음, 20 = 최대 흐림)."
         },
         "folderSettings": {
             "activeLibrary": "활성 라이브러리",

locales/ru.json

@@ -448,7 +448,9 @@
                 "modelName": "Название модели",
                 "fileName": "Имя файла"
             },
-            "modelNameDisplayHelp": "Выберите, что отображать в нижней части карточки модели"
+            "modelNameDisplayHelp": "Выберите, что отображать в нижней части карточки модели",
+            "cardBlurAmount": "Размытие наложения карточек",
+            "cardBlurAmountHelp": "Настройте интенсивность размытия наложений верхнего и нижнего колонтитулов на карточках моделей и рецептов (0 = без размытия, 20 = максимальное размытие)."
         },
         "folderSettings": {
             "activeLibrary": "Активная библиотека",

locales/zh-CN.json

@@ -448,7 +448,9 @@
                 "modelName": "模型名称",
                 "fileName": "文件名"
             },
-            "modelNameDisplayHelp": "选择在模型卡片底部显示的内容"
+            "modelNameDisplayHelp": "选择在模型卡片底部显示的内容",
+            "cardBlurAmount": "卡片叠加模糊强度",
+            "cardBlurAmountHelp": "调整模型和配方卡片上页眉和页脚叠加层的模糊强度（0 = 无模糊，20 = 最大模糊）。"
         },
         "folderSettings": {
             "activeLibrary": "活动库",

locales/zh-TW.json

@@ -448,7 +448,9 @@
                 "modelName": "模型名稱",
                 "fileName": "檔案名稱"
             },
-            "modelNameDisplayHelp": "選擇在模型卡片底部顯示的內容"
+            "modelNameDisplayHelp": "選擇在模型卡片底部顯示的內容",
+            "cardBlurAmount": "卡片疊加模糊強度",
+            "cardBlurAmountHelp": "調整模型和配方卡片上頁首和頁尾疊加層的模糊強度（0 = 無模糊，20 = 最大模糊）。"
         },
         "folderSettings": {
             "activeLibrary": "使用中的資料庫",

py/routes/handlers/model_handlers.py

@@ -1785,6 +1785,8 @@ class ModelDownloadHandler:
                 bytes_downloaded = 0
             total_bytes_raw = request.query.get("total_bytes")
             total_bytes = int(total_bytes_raw) if total_bytes_raw else None
+            completed_at_raw = request.query.get("completed_at")
+            completed_at = float(completed_at_raw) if completed_at_raw else None
 
             service = await DownloadQueueService.get_instance()
             item = await service.complete_download(
@@ -1794,6 +1796,7 @@ class ModelDownloadHandler:
                 file_path=file_path,
                 bytes_downloaded=bytes_downloaded,
                 total_bytes=total_bytes,
+                completed_at=completed_at,
             )
             if item is None:
                 return web.json_response(

py/routes/handlers/recipe_handlers.py

@@ -1597,15 +1597,8 @@ class RecipeManagementHandler:
 
             cache = await recipe_scanner.get_cached_data()
 
-            # Build lookup: image_id -> recipe_id from stored source_path
-            image_to_recipe = {}
-            for recipe in getattr(cache, "raw_data", []):
-                source = recipe.get("source_path")
-                if not source:
-                    continue
-                image_id = extract_civitai_image_id(source)
-                if image_id and image_id not in image_to_recipe:
-                    image_to_recipe[image_id] = recipe.get("id")
+            # Use precomputed image_id_map (built once at cache init)
+            image_to_recipe = getattr(cache, "image_id_map", {})
 
             results = {}
             for img_id in requested_ids:
@@ -1641,20 +1634,22 @@ class RecipeManagementHandler:
                     "Could not extract Civitai image ID from URL"
                 )
 
-            # Check for duplicate (fast, before acquiring semaphore), unless force
             if not force:
                 cache = await recipe_scanner.get_cached_data()
-                for recipe in getattr(cache, "raw_data", []):
-                    source = recipe.get("source_path")
-                    if source:
-                        existing_id = extract_civitai_image_id(source)
-                        if existing_id == image_id:
-                            return web.json_response({
-                                "success": True,
-                                "recipe_id": recipe.get("id"),
-                                "name": recipe.get("title", ""),
-                                "already_exists": True,
-                            })
+                image_to_recipe = getattr(cache, "image_id_map", {})
+                existing_recipe_id = image_to_recipe.get(image_id)
+                if existing_recipe_id:
+                    recipe_name = ""
+                    for recipe in getattr(cache, "raw_data", []):
+                        if str(recipe.get("id", "")) == existing_recipe_id:
+                            recipe_name = recipe.get("title", "") or ""
+                            break
+                    return web.json_response({
+                        "success": True,
+                        "recipe_id": existing_recipe_id,
+                        "name": recipe_name,
+                        "already_exists": True,
+                    })
 
             async with self._import_semaphore:
                 return await self._do_import_from_url(image_url, recipe_scanner)

py/services/download_queue_service.py

@@ -349,6 +349,7 @@ class DownloadQueueService:
         file_path: Optional[str] = None,
         bytes_downloaded: int = 0,
         total_bytes: Optional[int] = None,
+        completed_at: Optional[float] = None,
     ) -> Optional[dict[str, Any]]:
         """Atomically move a download from the queue into the history table.
 
@@ -356,6 +357,9 @@ class DownloadQueueService:
         queue, and inserts a corresponding history entry with the given
         terminal status (``completed``, ``failed``, or ``canceled``).
 
+        When *completed_at* is provided it is used as the completion
+        timestamp; otherwise ``time.time()`` is used.
+
         Returns the original queue record (before deletion) on success,
         or ``None`` if the download was not found in the queue.
         """
@@ -368,7 +372,7 @@ class DownloadQueueService:
             if row is None:
                 return None
 
-            now = time.time()
+            now = completed_at if completed_at is not None else time.time()
             conn.execute(
                 "DELETE FROM download_queue WHERE download_id = ?",
                 (download_id,),

py/services/downloader.py

@@ -256,7 +256,9 @@ class Downloader:
                 self._session = None
 
         # Check for app-level proxy settings
-        proxy_url = None
+        proxy_url = None  # http(s) proxy, passed via the per-request `proxy=` kwarg
+        socks_proxy_url = None  # SOCKS proxy, handled via aiohttp-socks connector
+        app_proxy_active = False
         settings_manager = get_settings_manager()
         if settings_manager.get("proxy_enabled", False):
             proxy_host = settings_manager.get("proxy_host", "").strip()
@@ -268,9 +270,19 @@ class Downloader:
             if proxy_host and proxy_port:
                 # Build proxy URL
                 if proxy_username and proxy_password:
-                    proxy_url = f"{proxy_type}://{proxy_username}:{proxy_password}@{proxy_host}:{proxy_port}"
+                    full_proxy_url = f"{proxy_type}://{proxy_username}:{proxy_password}@{proxy_host}:{proxy_port}"
                 else:
-                    proxy_url = f"{proxy_type}://{proxy_host}:{proxy_port}"
+                    full_proxy_url = f"{proxy_type}://{proxy_host}:{proxy_port}"
+
+                app_proxy_active = True
+                # aiohttp cannot tunnel SOCKS via the per-request `proxy=` kwarg
+                # (it would send HTTP to the SOCKS port and fail parsing the
+                # SOCKS handshake reply). SOCKS must be handled by an
+                # aiohttp-socks ProxyConnector instead.
+                if proxy_type.startswith("socks"):
+                    socks_proxy_url = full_proxy_url
+                else:
+                    proxy_url = full_proxy_url
 
                 logger.debug(
                     f"Using app-level proxy: {proxy_type}://{proxy_host}:{proxy_port}"
@@ -294,13 +306,27 @@ class Downloader:
             logger.debug("SSL: certifi unavailable; using system default CA bundle")
 
         # Optimize TCP connection parameters
-        connector = aiohttp.TCPConnector(
+        connector_kwargs = dict(
             ssl=ssl_context,
             limit=8,  # Concurrent connections
             ttl_dns_cache=300,  # DNS cache timeout
             force_close=False,  # Keep connections for reuse
             enable_cleanup_closed=True,
         )
+        if socks_proxy_url:
+            # Route all traffic through the SOCKS proxy via aiohttp-socks. The
+            # connector tunnels every connection, so no per-request `proxy=` is
+            # used (and must not be — see self._proxy_url below).
+            try:
+                from aiohttp_socks import ProxyConnector
+            except ImportError as e:  # pragma: no cover
+                raise RuntimeError(
+                    "A SOCKS proxy is configured but the 'aiohttp-socks' package "
+                    "is not installed. Install it with: pip install aiohttp-socks"
+                ) from e
+            connector = ProxyConnector.from_url(socks_proxy_url, **connector_kwargs)
+        else:
+            connector = aiohttp.TCPConnector(**connector_kwargs)
 
         # Configure timeout parameters
         timeout = aiohttp.ClientTimeout(
@@ -311,12 +337,14 @@ class Downloader:
 
         self._session = aiohttp.ClientSession(
             connector=connector,
-            trust_env=proxy_url
-            is None,  # Only use system proxy if no app-level proxy is set
+            # Only fall back to system/env proxy when no app-level proxy is active
+            trust_env=not app_proxy_active,
             timeout=timeout,
         )
 
-        # Store proxy URL for use in requests
+        # Store proxy URL for per-request use. Stays None for SOCKS because the
+        # ProxyConnector already tunnels everything; passing proxy= for SOCKS
+        # would re-trigger the original aiohttp parse error.
         self._proxy_url = proxy_url
         self._session_created_at = datetime.now()
 

py/services/persistent_recipe_cache.py

@@ -12,7 +12,7 @@ import logging
 import os
 import sqlite3
 import threading
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Dict, List, Optional, Set, Tuple
 
 from ..utils.cache_paths import CacheType, resolve_cache_path_with_migration
@@ -26,6 +26,8 @@ class PersistedRecipeData:
 
     raw_data: List[Dict]
     file_stats: Dict[str, Tuple[float, int]]  # json_path -> (mtime, size)
+    image_id_map: Dict[str, str] = field(default_factory=dict)
+    """Precomputed mapping of civitai image_id → recipe_id."""
 
 
 class PersistentRecipeCache:
@@ -116,6 +118,20 @@ class PersistentRecipeCache:
                     if not rows:
                         return None
 
+                    # Restore precomputed image_id_map if available
+                    image_id_map: Dict[str, str] = {}
+                    try:
+                        meta_row = conn.execute(
+                            "SELECT value FROM cache_metadata WHERE key = ?",
+                            ("image_id_map",),
+                        ).fetchone()
+                        if meta_row:
+                            parsed = json.loads(meta_row["value"])
+                            if isinstance(parsed, dict):
+                                image_id_map = parsed
+                    except Exception:
+                        pass  # missing or corrupt — rebuilt on next cache refresh
+
                 finally:
                     conn.close()
         except FileNotFoundError:
@@ -138,14 +154,24 @@ class PersistentRecipeCache:
                     row["file_size"] or 0,
                 )
 
-        return PersistedRecipeData(raw_data=raw_data, file_stats=file_stats)
+        return PersistedRecipeData(
+            raw_data=raw_data,
+            file_stats=file_stats,
+            image_id_map=image_id_map,
+        )
 
-    def save_cache(self, recipes: List[Dict], json_paths: Optional[Dict[str, str]] = None) -> None:
+    def save_cache(
+        self,
+        recipes: List[Dict],
+        json_paths: Optional[Dict[str, str]] = None,
+        image_id_map: Optional[Dict[str, str]] = None,
+    ) -> None:
         """Save all recipes to SQLite cache.
 
         Args:
             recipes: List of recipe dictionaries to persist.
             json_paths: Optional mapping of recipe_id -> json_path for file stats.
+            image_id_map: Optional precomputed civitai image_id → recipe_id mapping.
         """
         if not self.is_enabled():
             return
@@ -186,6 +212,12 @@ class PersistentRecipeCache:
                             recipe_rows,
                         )
 
+                    # Persist image_id_map for O(1) lookups on cache load
+                    conn.execute(
+                        "INSERT OR REPLACE INTO cache_metadata (key, value) VALUES (?, ?)",
+                        ("image_id_map", json.dumps(image_id_map or {})),
+                    )
+
                     conn.commit()
                     logger.debug("Persisted %d recipes to cache", len(recipe_rows))
                 finally:
@@ -273,6 +305,29 @@ class PersistentRecipeCache:
         except Exception as exc:
             logger.debug("Failed to remove recipe %s from cache: %s", recipe_id, exc)
 
+    def save_image_id_map(self, image_id_map: Dict[str, str]) -> None:
+        """Persist the image_id_map to cache_metadata without rewriting the full cache.
+
+        This is called after ``add_recipe`` / ``remove_recipe`` mutations so
+        the persistent copy does not go stale between full ``save_cache`` calls.
+        """
+        if not self.is_enabled() or not self._schema_initialized:
+            return
+
+        try:
+            with self._db_lock:
+                conn = self._connect()
+                try:
+                    conn.execute(
+                        "INSERT OR REPLACE INTO cache_metadata (key, value) VALUES (?, ?)",
+                        ("image_id_map", json.dumps(image_id_map)),
+                    )
+                    conn.commit()
+                finally:
+                    conn.close()
+        except Exception as exc:
+            logger.debug("Failed to persist image_id_map: %s", exc)
+
     def get_indexed_recipe_ids(self) -> Set[str]:
         """Return all recipe IDs in the cache.
 

py/services/recipe_cache.py

@@ -1,6 +1,6 @@
 import asyncio
 from typing import Iterable, List, Dict, Optional
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from operator import itemgetter
 from natsort import natsorted
 
@@ -14,6 +14,15 @@ class RecipeCache:
     sorted_by_date: List[Dict]
     folders: List[str] | None = None
     folder_tree: Dict | None = None
+    image_id_map: Dict[str, str] = field(default_factory=dict)
+    """Mapping of civitai image_id → recipe_id, precomputed at cache build time.
+
+    Built once during cache initialization (O(n)) so that
+    ``check_image_exists`` and ``import_from_url`` duplicate checks
+    can look up image_id in O(1) instead of scanning all recipes.
+    Recipes imported from local files have no valid civitai image_id
+    and are naturally excluded from this map.
+    """
 
     def __post_init__(self):
         self._lock = asyncio.Lock()

py/services/recipe_scanner.py

@@ -20,6 +20,7 @@ from .metadata_service import get_default_metadata_provider
 from .checkpoint_scanner import CheckpointScanner
 from .settings_manager import get_settings_manager
 from .recipes.errors import RecipeNotFoundError
+from ..utils.civitai_utils import extract_civitai_image_id
 from ..utils.utils import calculate_recipe_fingerprint, fuzzy_match
 from natsort import natsorted
 import sys
@@ -532,7 +533,21 @@ class RecipeScanner:
                     self._sort_cache_sync()
                     # Backfill source_path from JSON files if missing (schema migration)
                     if self._backfill_source_path_if_needed(recipes, json_paths):
-                        self._persistent_cache.save_cache(recipes, json_paths)
+                        self._cache.image_id_map = self._build_image_id_map()
+                        self._persistent_cache.save_cache(
+                            recipes, json_paths, self._cache.image_id_map
+                        )
+                    else:
+                        # Use persisted map, or rebuild if empty (e.g. first startup
+                        # after deploying the image_id_map feature).
+                        if persisted.image_id_map:
+                            self._cache.image_id_map = dict(persisted.image_id_map)
+                        else:
+                            self._cache.image_id_map = self._build_image_id_map()
+                            if self._cache.image_id_map:
+                                self._persistent_cache.save_image_id_map(
+                                    self._cache.image_id_map
+                                )
                     return self._cache
                 else:
                     # Partial update: some files changed
@@ -545,8 +560,11 @@ class RecipeScanner:
                     self._sort_cache_sync()
                     # Backfill source_path from JSON files if missing (schema migration)
                     self._backfill_source_path_if_needed(recipes, json_paths)
+                    self._cache.image_id_map = self._build_image_id_map()
                     # Persist updated cache
-                    self._persistent_cache.save_cache(recipes, json_paths)
+                    self._persistent_cache.save_cache(
+                        recipes, json_paths, self._cache.image_id_map
+                    )
                     return self._cache
 
             # Fall back to full directory scan
@@ -558,9 +576,12 @@ class RecipeScanner:
             self._cache.raw_data = recipes
             self._update_folder_metadata(self._cache)
             self._sort_cache_sync()
+            self._cache.image_id_map = self._build_image_id_map()
 
             # Persist for next startup
-            self._persistent_cache.save_cache(recipes, json_paths)
+            self._persistent_cache.save_cache(
+                recipes, json_paths, self._cache.image_id_map
+            )
 
             return self._cache
         except Exception as e:
@@ -832,6 +853,28 @@ class RecipeScanner:
         except Exception as e:
             logger.error(f"Error sorting recipe cache: {e}")
 
+    def _build_image_id_map(self) -> Dict[str, str]:
+        """Build civitai image_id → recipe_id mapping from cached recipes.
+
+        Only recipes with a valid CivitAI image URL source_path produce an
+        entry.  Recipes imported from local files are naturally excluded.
+        """
+        mapping: Dict[str, str] = {}
+        if not self._cache:
+            return mapping
+        for recipe in getattr(self._cache, "raw_data", []):
+            if not isinstance(recipe, dict):
+                continue
+            source = recipe.get("source_path")
+            if not source:
+                continue
+            image_id = extract_civitai_image_id(source)
+            if image_id and image_id not in mapping:
+                recipe_id = recipe.get("id")
+                if recipe_id is not None:
+                    mapping[image_id] = str(recipe_id)
+        return mapping
+
     async def _wait_for_lora_scanner(self) -> None:
         """Ensure the LoRA scanner has initialized before recipe enrichment."""
 
@@ -1296,11 +1339,20 @@ class RecipeScanner:
         # Update FTS index
         self._update_fts_index_for_recipe(recipe_data, "add")
 
+        source = recipe_data.get("source_path")
+        if source:
+            image_id = extract_civitai_image_id(source)
+            if image_id:
+                recipe_id_value = recipe_data.get("id")
+                if recipe_id_value is not None:
+                    cache.image_id_map[image_id] = str(recipe_id_value)
+
         # Persist to SQLite cache
         if self._persistent_cache:
             recipe_id = str(recipe_data.get("id", ""))
             json_path = self._json_path_map.get(recipe_id, "")
             self._persistent_cache.update_recipe(recipe_data, json_path)
+            self._persistent_cache.save_image_id_map(cache.image_id_map)
 
     async def remove_recipe(self, recipe_id: str) -> bool:
         """Remove a recipe from the cache by ID."""
@@ -1319,9 +1371,15 @@ class RecipeScanner:
         # Update FTS index
         self._update_fts_index_for_recipe(recipe_id, "remove")
 
+        # Remove any image_id entry pointing to this recipe
+        stale = [k for k, v in cache.image_id_map.items() if v == recipe_id]
+        for k in stale:
+            del cache.image_id_map[k]
+
         # Remove from SQLite cache
         if self._persistent_cache:
             self._persistent_cache.remove_recipe(recipe_id)
+            self._persistent_cache.save_image_id_map(cache.image_id_map)
             self._json_path_map.pop(recipe_id, None)
 
         return True
@@ -1332,14 +1390,21 @@ class RecipeScanner:
         cache = await self.get_cached_data()
         removed = await cache.bulk_remove(recipe_ids, resort=False)
         if removed:
+            removed_ids = {str(r.get("id", "")) for r in removed}
+            stale = [k for k, v in cache.image_id_map.items() if v in removed_ids]
+            for k in stale:
+                del cache.image_id_map[k]
+
             self._schedule_resort()
-            # Update FTS index and persistent cache for each removed recipe
             for recipe in removed:
                 recipe_id = str(recipe.get("id", ""))
                 self._update_fts_index_for_recipe(recipe_id, "remove")
                 if self._persistent_cache:
                     self._persistent_cache.remove_recipe(recipe_id)
                     self._json_path_map.pop(recipe_id, None)
+
+            if self._persistent_cache:
+                self._persistent_cache.save_image_id_map(cache.image_id_map)
         return len(removed)
 
     async def scan_all_recipes(self) -> List[Dict]:

requirements.txt

@@ -1,4 +1,5 @@
 aiohttp
+aiohttp-socks
 jinja2
 safetensors
 piexif

static/css/components/card.css

@@ -278,7 +278,7 @@
     left: 0;
     right: 0;
     background: linear-gradient(transparent 15%, oklch(0% 0 0 / 0.75));
-    backdrop-filter: blur(8px);
+    backdrop-filter: blur(var(--card-blur-amount, 8px));
     color: white;
     padding: var(--space-1);
     display: flex;
@@ -294,7 +294,7 @@
     left: 0;
     right: 0;
     background: linear-gradient(oklch(0% 0 0 / 0.75), transparent 85%);
-    backdrop-filter: blur(8px);
+    backdrop-filter: blur(var(--card-blur-amount, 8px));
     color: white;
     padding: var(--space-1);
     display: flex;

static/css/components/modal/settings-modal.css

@@ -813,6 +813,67 @@
     outline: none;
 }
 
+/* Range Slider Control */
+.range-control {
+    width: 100%;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    justify-content: flex-end;
+}
+
+.range-control input[type="range"] {
+    width: 120px;
+    height: 4px;
+    -webkit-appearance: none;
+    appearance: none;
+    background: var(--border-color);
+    border-radius: 2px;
+    outline: none;
+    cursor: pointer;
+    flex-shrink: 0;
+}
+
+.range-control input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    background: var(--lora-accent);
+    cursor: pointer;
+    border: 2px solid var(--lora-surface);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+    transition: transform 0.15s ease;
+}
+
+.range-control input[type="range"]::-webkit-slider-thumb:hover {
+    transform: scale(1.15);
+}
+
+.range-control input[type="range"]::-moz-range-thumb {
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    background: var(--lora-accent);
+    cursor: pointer;
+    border: 2px solid var(--lora-surface);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+}
+
+.range-control .range-value {
+    min-width: 36px;
+    text-align: center;
+    font-size: 0.9em;
+    font-weight: 600;
+    color: var(--text-color);
+    font-variant-numeric: tabular-nums;
+}
+
+[data-theme="dark"] .range-control input[type="range"] {
+    background: rgba(255, 255, 255, 0.15);
+}
+
 /* Toggle Switch */
 .toggle-switch {
     position: relative;

static/js/managers/SettingsManager.js

@@ -804,6 +804,16 @@ export class SettingsManager {
             );
         }
 
+        // Set card blur amount slider
+        const cardBlurAmountInput = document.getElementById('cardBlurAmount');
+        if (cardBlurAmountInput) {
+            cardBlurAmountInput.value = state.global.settings.card_blur_amount ?? 8;
+        }
+        const cardBlurAmountValue = document.getElementById('cardBlurAmountValue');
+        if (cardBlurAmountValue) {
+            cardBlurAmountValue.textContent = `${state.global.settings.card_blur_amount ?? 8}px`;
+        }
+
         const usePortableCheckbox = document.getElementById('usePortableSettings');
         if (usePortableCheckbox) {
             usePortableCheckbox.checked = !!state.global.settings.use_portable_settings;
@@ -2051,6 +2061,28 @@ export class SettingsManager {
         }
     }
 
+    async saveRangeSetting(elementId, displayId, settingKey) {
+        const element = document.getElementById(elementId);
+        if (!element) return;
+
+        const value = parseInt(element.value, 10);
+
+        try {
+            await this.saveSetting(settingKey, value);
+            this.applyFrontendSettings();
+
+            // Update the displayed value next to the slider
+            const displayEl = document.getElementById(displayId);
+            if (displayEl) {
+                displayEl.textContent = `${value}px`;
+            }
+
+            showToast('toast.settings.settingsUpdated', { setting: settingKey.replace(/_/g, ' ') }, 'success');
+        } catch (error) {
+            showToast('toast.settings.settingSaveFailed', { message: error.message }, 'error');
+        }
+    }
+
     updateExampleImagesOpenSettingsVisibility() {
         const openMode = state.global.settings.example_images_open_mode || 'system';
         const localRootSetting = document.getElementById('exampleImagesLocalRootSetting');
@@ -2887,6 +2919,10 @@ export class SettingsManager {
     }
 
     applyFrontendSettings() {
+        // Apply card blur amount to CSS custom property
+        const cardBlurAmount = state.global.settings.card_blur_amount ?? 8;
+        document.documentElement.style.setProperty('--card-blur-amount', `${cardBlurAmount}px`);
+
         // Apply autoplay setting to existing videos in card previews
         const autoplayOnHover = state.global.settings.autoplay_on_hover;
         document.querySelectorAll('.card-preview video').forEach(video => {

static/js/state/index.js

@@ -32,6 +32,7 @@ const DEFAULT_SETTINGS_BASE = Object.freeze({
     auto_download_example_images: false,
     blur_mature_content: true,
     mature_blur_level: 'R',
+    card_blur_amount: 8,
     autoplay_on_hover: false,
     display_density: 'default',
     card_info_display: 'always',

templates/components/modals/settings_modal.html

@@ -448,6 +448,7 @@
                                     </div>
                                 </div>
                             </div>
+
                         </div>
                         
                         <!-- Video Settings -->
@@ -556,6 +557,23 @@
                                 </div>
                             </div>
 
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="cardBlurAmount">
+                                        {{ t('settings.layoutSettings.cardBlurAmount') }}
+                                        <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.layoutSettings.cardBlurAmountHelp') }}"></i>
+                                    </label>
+                                    </div>
+                                    <div class="setting-control range-control">
+                                        <input type="range" id="cardBlurAmount" min="0" max="20" value="8" step="1"
+                                               oninput="document.getElementById('cardBlurAmountValue').textContent = this.value + 'px'"
+                                               onchange="settingsManager.saveRangeSetting('cardBlurAmount', 'cardBlurAmountValue', 'card_blur_amount')">
+                                        <span id="cardBlurAmountValue" class="range-value">8px</span>
+                                    </div>
+                                </div>
+                            </div>
+
                             <div class="setting-item">
                                 <div class="setting-row">
                                     <div class="setting-info">

tests/routes/test_recipe_routes.py

@@ -46,6 +46,7 @@ class StubRecipeScanner:
         self.last_paginated_params: Dict[str, Any] | None = None
         self.lora_lookup: Dict[str, List[Dict[str, Any]]] = {}
         self.checkpoint_lookup: Dict[str, List[Dict[str, Any]]] = {}
+        self.image_id_map_override: Dict[str, str] = {}
 
         async def _noop_get_cached_data(force_refresh: bool = False) -> None:  # noqa: ARG001 - signature mirrors real scanner
             return None
@@ -56,7 +57,10 @@ class StubRecipeScanner:
         )
 
     async def get_cached_data(self, force_refresh: bool = False) -> SimpleNamespace:  # noqa: ARG002 - flag unused by stub
-        return SimpleNamespace(raw_data=list(self.cached_raw))
+        return SimpleNamespace(
+            raw_data=list(self.cached_raw),
+            image_id_map=dict(getattr(self, "image_id_map_override", {})),
+        )
 
     async def get_paginated_data(self, **params: Any) -> Dict[str, Any]:
         self.last_paginated_params = params
@@ -999,3 +1003,95 @@ async def test_batch_import_cancel_missing_id(monkeypatch, tmp_path: Path) -> No
         payload = await response.json()
         assert response.status == 400
         assert payload["success"] is False
+
+
+async def test_check_image_exists_uses_image_id_map(monkeypatch, tmp_path: Path) -> None:
+    """check_image_exists must use precomputed image_id_map instead of scanning raw_data."""
+    async with recipe_harness(monkeypatch, tmp_path) as harness:
+        harness.scanner.image_id_map_override = {
+            "123": "recipe-alpha",
+            "789": "recipe-gamma",
+        }
+
+        response = await harness.client.get(
+            "/api/lm/recipes/check-image-exists",
+            params={"image_ids": "123,456,789"},
+        )
+        payload = await response.json()
+
+        assert response.status == 200
+        assert payload["success"] is True
+        assert payload["results"]["123"] == {
+            "in_library": True,
+            "recipe_id": "recipe-alpha",
+        }
+        assert payload["results"]["456"] == {
+            "in_library": False,
+            "recipe_id": None,
+        }
+        assert payload["results"]["789"] == {
+            "in_library": True,
+            "recipe_id": "recipe-gamma",
+        }
+
+
+async def test_check_image_exists_handles_empty_input(monkeypatch, tmp_path: Path) -> None:
+    """Empty or non-numeric image_ids must return an empty results dict."""
+    async with recipe_harness(monkeypatch, tmp_path) as harness:
+        response = await harness.client.get(
+            "/api/lm/recipes/check-image-exists",
+            params={"image_ids": ""},
+        )
+        payload = await response.json()
+        assert response.status == 200
+        assert payload["results"] == {}
+
+
+async def test_import_from_url_detects_duplicate_via_image_id_map(
+    monkeypatch, tmp_path: Path,
+) -> None:
+    """import_from_url must return already_exists when image_id is in image_id_map."""
+    async with recipe_harness(monkeypatch, tmp_path) as harness:
+        harness.scanner.cached_raw = [
+            {"id": "existing-recipe", "title": "My Recipe"},
+        ]
+        harness.scanner.image_id_map_override = {
+            "99999": "existing-recipe",
+        }
+
+        response = await harness.client.get(
+            "/api/lm/recipes/import-from-url",
+            params={"image_url": "https://civitai.com/images/99999"},
+        )
+        payload = await response.json()
+
+        assert response.status == 200
+        assert payload["already_exists"] is True
+        assert payload["recipe_id"] == "existing-recipe"
+        assert payload["name"] == "My Recipe"
+
+
+async def test_import_from_url_proceeds_when_image_id_not_in_map(
+    monkeypatch, tmp_path: Path,
+) -> None:
+    """When image_id is absent from image_id_map, import_from_url must proceed to import."""
+    async with recipe_harness(monkeypatch, tmp_path) as harness:
+        harness.scanner.image_id_map_override = {
+            "111": "some-other-recipe",
+        }
+        harness.civitai.image_info["99999"] = {
+            "id": 99999,
+            "url": "https://image.civitai.com/x/y/original=true/sample.jpeg",
+            "type": "image",
+            "meta": {"prompt": "test"},
+        }
+
+        response = await harness.client.get(
+            "/api/lm/recipes/import-from-url",
+            params={"image_url": "https://civitai.com/images/99999"},
+        )
+
+        # The import may succeed or fail depending on downstream stubs,
+        # but it must NOT return already_exists
+        payload = await response.json()
+        assert payload.get("already_exists") is not True

tests/services/test_recipe_scanner.py

@@ -1015,3 +1015,85 @@ async def test_get_paginated_data_sorting(recipe_scanner):
     # Test Date ASC: Gamma (5), Alpha (10), Beta (20)
     res = await scanner.get_paginated_data(page=1, page_size=10, sort_by="date:asc")
     assert [i["id"] for i in res["items"]] == ["C", "A", "B"]
+
+
+async def test_build_image_id_map_filters_correctly(recipe_scanner):
+    """Only recipes with valid CivitAI source_path appear in image_id_map.
+
+    Recipes imported from local files or with empty/missing source_path
+    must be naturally excluded.
+    """
+    scanner, _ = recipe_scanner
+    from py.services.recipe_cache import RecipeCache
+
+    scanner._cache = RecipeCache(
+        raw_data=[
+            {"id": "r1", "source_path": "https://civitai.com/images/12345"},
+            {"id": "r2", "source_path": "https://civitai.com/images/67890"},
+            {"id": "r3", "source_path": "/home/user/local_image.png"},
+            {"id": "r4", "source_path": ""},
+            {"id": "r5"},
+        ],
+        sorted_by_name=[],
+        sorted_by_date=[],
+    )
+
+    result = scanner._build_image_id_map()
+
+    assert result == {
+        "12345": "r1",
+        "67890": "r2",
+    }
+    # r3 = local file path, r4 = empty string, r5 = no key → all excluded
+    for rid in ("r3", "r4", "r5"):
+        assert rid not in result.values()
+
+
+async def test_add_recipe_updates_image_id_map(recipe_scanner):
+    """Adding a recipe with a CivitAI URL must update image_id_map.
+
+    A recipe with a local file path must NOT produce an entry.
+    """
+    scanner, _ = recipe_scanner
+
+    await scanner.add_recipe({
+        "id": "civitai-recipe",
+        "title": "CivitAI",
+        "source_path": "https://civitai.com/images/55555",
+    })
+
+    cache = await scanner.get_cached_data()
+    assert cache.image_id_map.get("55555") == "civitai-recipe"
+
+    await scanner.add_recipe({
+        "id": "local-recipe",
+        "title": "Local",
+        "source_path": "/path/to/local.png",
+    })
+
+    assert "local-recipe" not in cache.image_id_map.values()
+
+
+async def test_remove_recipe_clears_image_id_map(recipe_scanner):
+    """Removing a recipe that has a CivitAI image_id must clean up the map."""
+    scanner, _ = recipe_scanner
+
+    await scanner.add_recipe({
+        "id": "recipe-a",
+        "title": "A",
+        "source_path": "https://civitai.com/images/111",
+    })
+    await scanner.add_recipe({
+        "id": "recipe-b",
+        "title": "B",
+        "source_path": "https://civitai.com/images/222",
+    })
+
+    cache = await scanner.get_cached_data()
+    assert "111" in cache.image_id_map
+    assert cache.image_id_map["222"] == "recipe-b"
+
+    await scanner.remove_recipe("recipe-a")
+
+    assert "111" not in cache.image_id_map
+    assert cache.image_id_map["222"] == "recipe-b"

tests/test_persistent_recipe_cache.py

@@ -465,3 +465,81 @@ class TestPersistentRecipeCache:
         # Operations should complete
         assert operation_counts["saves"] == 5
         assert operation_counts["removes"] == 5
+
+    # -----------------------------------------------------------------------
+    # image_id_map persistence (Phase 1 improvement)
+    # -----------------------------------------------------------------------
+
+    def test_save_and_load_image_id_map_roundtrip(self, temp_db_path, sample_recipes):
+        """Save image_id_map via save_cache() and verify it round-trips through load_cache()."""
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+
+        image_id_map = {
+            "12345": "recipe-alpha",
+            "67890": "recipe-beta",
+        }
+        cache.save_cache(sample_recipes, image_id_map=image_id_map)
+
+        loaded = cache.load_cache()
+        assert loaded is not None
+        assert loaded.image_id_map == image_id_map
+
+    def test_load_without_image_id_map_returns_empty_dict(self, temp_db_path, sample_recipes):
+        """Loading from a cache that has no image_id_map metadata must yield {}."""
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+
+        # Save without image_id_map
+        cache.save_cache(sample_recipes)
+
+        loaded = cache.load_cache()
+        assert loaded is not None
+        assert loaded.image_id_map == {}
+
+    def test_save_cache_without_image_id_map_does_not_corrupt_existing(
+        self, temp_db_path, sample_recipes,
+    ):
+        """Overwriting cache without passing image_id_map must not leave stale data.
+
+        The previous image_id_map entry in cache_metadata should be replaced with {}.
+        """
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+
+        cache.save_cache(sample_recipes, image_id_map={"123": "old-recipe"})
+        # Overwrite without image_id_map
+        cache.save_cache(sample_recipes)
+
+        loaded = cache.load_cache()
+        assert loaded.image_id_map == {}
+
+    def test_image_id_map_survives_recipe_update(self, temp_db_path, sample_recipes):
+        """Updating a single recipe must not drop the image_id_map metadata."""
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+
+        cache.save_cache(sample_recipes, image_id_map={"123": "recipe-alpha"})
+
+        updated = dict(sample_recipes[0])
+        updated["title"] = "Updated"
+        cache.update_recipe(updated)
+
+        loaded = cache.load_cache()
+        assert loaded.image_id_map == {"123": "recipe-alpha"}
+
+    def test_save_image_id_map_persists_without_full_save(self, temp_db_path, sample_recipes):
+        """save_image_id_map must update cache_metadata without rewriting all recipes."""
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+        cache.save_cache(sample_recipes)
+
+        cache.save_image_id_map({"555": "new-recipe", "666": "another-recipe"})
+
+        loaded = cache.load_cache()
+        assert loaded.image_id_map == {"555": "new-recipe", "666": "another-recipe"}
+
+    def test_save_image_id_map_overwrites_previous(self, temp_db_path, sample_recipes):
+        """Calling save_image_id_map twice must replace, not merge."""
+        cache = PersistentRecipeCache(db_path=temp_db_path)
+        cache.save_cache(sample_recipes, image_id_map={"111": "old"})
+
+        cache.save_image_id_map({"222": "new-only"})
+
+        loaded = cache.load_cache()
+        assert loaded.image_id_map == {"222": "new-only"}