feat(scanner): scan a single root and keep unreachable entries (#1108)

Refreshing had no way to say "scan only this drive": a user with three external
drives had to spin all of them up for every refresh, and switching a drive off
made the next refresh treat its whole library as deleted (rows pruned from the
memory cache and the SQLite cache, preview_url stripped on the next scroll).

Backend (py/services/model_scanner.py, py/config.py):
* ReconcileScope(roots, folder) + _reconcile_cache(scope=...): files inside the
  scope reconcile normally, everything outside is neither re-read nor removed.
  The folder half is plumbing for the sidebar entry in the next change.
* Path-level pruning guard: cached entries under a path this walk could not
  read are kept and reported instead of removed. Sources: a configured root that
  is not reachable (drive switched off while LM runs), a directory os.walk
  failed to enter (permissions / I/O error / Windows junction to an offline
  drive), and a known first-level symlink whose target is gone
  (Config.iter_path_mappings()).
* The recorded folder list is unioned instead of replaced whenever the scan did
  not verify every root, so a scoped scan cannot empty the sidebar.
* _reconcile_cache returns a summary (added / removed / repaired /
  scanned_roots / skipped_roots / unavailable_paths / kept_unreachable),
  exposed as ModelScanner.last_reconcile_summary, returned by
  BaseModelService.scan_models() and broadcast in the completed WS payload.
* _root_display_labels(): set-aware labels ("G: loras", "usb/loras") grown
  leftwards with real parent segments until unique, shared by the walk-progress
  line and the roots API.
* GET /scan accepts repeated `roots` (400 for unknown roots, 400 combined with
  full_rebuild=true); GET /roots gains root_details (label / reachable / cached
  count) while `roots` stays a plain path list for existing callers.
* serve_preview: a 404 no longer clears the cached preview_url when the file's
  own directory is unreachable - browsing the grid with a drive off used to
  strip preview references from the persistent cache.

Frontend:
* Refresh ▾ gains a "Scan one folder" section listing the page's roots with
  their cached counts; offline roots stay clickable and explain themselves; rows
  are wired by delegation (new static/js/components/controls/ScanScopeMenu.js).
* A scoped scan reports "Scanned <root>: N new, M removed"; a scan that kept
  entries reports "<N> models kept: <paths> not reachable".
* registerAPI() now injects the two cross-page passthroughs (fetchModelRoots and
  an argument-forwarding refreshModels) so a page facade cannot drop them: the
  first version rendered an empty menu and would have run a full refresh.
* createToastElement whitelists toast types, so a wrong `type` argument degrades
  to the info style instead of rendering an unstyled box.

Verified in a sandbox instance with three roots: a scoped scan walks only the
requested root (progress roots=0/1, 240 files); a full refresh with one root
offline reports kept_unreachable=60 and leaves all 420 models cached; /roots
reports the offline root with its cached count. 3699 passed, 7 skipped;
frontend 1488 passed (148 files); vue widgets 96 passed.

py/routes/handlers/model_handlers.py

@@ -26,6 +26,7 @@ from ...services.connectivity_guard import (
 )
 from ...services.metadata_sync_service import MetadataSyncService
 from ...services.model_file_service import ModelMoveService
+from ...services.model_scanner import ReconcileScope
 from ...services.preview_asset_service import PreviewAssetService
 from ...services.service_registry import ServiceRegistry
 from ...services.settings_manager import SettingsManager, get_settings_manager
@@ -1139,8 +1140,30 @@ class ModelQueryHandler:
     async def scan_models(self, request: web.Request) -> web.Response:
         try:
             full_rebuild = request.query.get("full_rebuild", "false").lower() == "true"
-            await self._service.scan_models(
-                force_refresh=True, rebuild_cache=full_rebuild
+            requested_roots = [
+                value for value in request.query.getall("roots", []) if value
+            ]
+            if requested_roots and full_rebuild:
+                return web.json_response(
+                    {
+                        "error": "Scoped scans are not supported with "
+                        "full_rebuild=true; a full rebuild always walks every root"
+                    },
+                    status=400,
+                )
+
+            scope = None
+            if requested_roots:
+                configured = self._service.get_model_roots()
+                unknown = [root for root in requested_roots if root not in configured]
+                if unknown:
+                    return web.json_response(
+                        {"error": "Unknown model root(s)", "roots": unknown}, status=400
+                    )
+                scope = ReconcileScope(roots=tuple(requested_roots))
+
+            summary = await self._service.scan_models(
+                force_refresh=True, rebuild_cache=full_rebuild, scope=scope
             )
             _broadcast_models_changed()
             if self._service.scanner.is_cancelled():
@@ -1150,12 +1173,13 @@ class ModelQueryHandler:
                         "message": f"{self._service.model_type.capitalize()} scan cancelled",
                     }
                 )
-            return web.json_response(
-                {
-                    "status": "success",
-                    "message": f"{self._service.model_type.capitalize()} scan completed",
-                }
-            )
+            payload: Dict[str, Any] = {
+                "status": "success",
+                "message": f"{self._service.model_type.capitalize()} scan completed",
+            }
+            if summary:
+                payload.update(summary)
+            return web.json_response(payload)
         except Exception as exc:
             self._logger.error(
                 "Error scanning %ss: %s", self._service.model_type, exc, exc_info=True
@@ -1165,7 +1189,14 @@ class ModelQueryHandler:
     async def get_model_roots(self, request: web.Request) -> web.Response:
         try:
             roots = self._service.get_model_roots()
-            return web.json_response({"success": True, "roots": roots})
+            try:
+                root_details = self._service.describe_model_roots()
+            except Exception as exc:  # pragma: no cover - defensive
+                self._logger.debug("Root details unavailable: %s", exc)
+                root_details = []
+            return web.json_response(
+                {"success": True, "roots": roots, "root_details": root_details}
+            )
         except Exception as exc:
             self._logger.error(
                 "Error getting %s roots: %s",

py/routes/handlers/preview_handlers.py

@@ -54,7 +54,18 @@ class PreviewHandler:
 
         if not resolved.is_file():
             logger.debug("Preview file not found at %s", str(resolved))
-            asyncio.create_task(self._cleanup_stale_preview_url(normalized))
+            if resolved.parent.is_dir():
+                # The file is really gone from a reachable directory, so the
+                # cached preview_url is stale and can be cleared.
+                asyncio.create_task(self._cleanup_stale_preview_url(normalized))
+            else:
+                # The directory itself is unreachable (drive switched off,
+                # unmounted share). Nothing was deleted: keep the cached
+                # preview_url so the card recovers when the drive is back.
+                logger.debug(
+                    "Preview directory unreachable, keeping cached preview_url: %s",
+                    str(resolved.parent),
+                )
             raise web.HTTPNotFound(text="Preview file not found")
 
         # aiohttp's FileResponse handles range requests, content headers, and