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.

tests/frontend/api/baseModelApi.refresh.test.js

@@ -153,8 +153,8 @@ describe('BaseModelApiClient.refreshModels scan progress', () => {
     };
   }
 
-  async function startRefresh(client, fullRebuild = false) {
-    const promise = client.refreshModels(fullRebuild);
+  async function startRefresh(client, fullRebuild = false, options = {}) {
+    const promise = client.refreshModels(fullRebuild, options);
     await vi.waitFor(() => {
       expect(FakeWebSocket.instances.length).toBe(1);
     });
@@ -392,6 +392,75 @@ describe('BaseModelApiClient.refreshModels scan progress', () => {
     await promise;
   });
 
+  it('requests a scoped scan when roots are passed', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: 'success' }),
+    });
+
+    const client = await createClient();
+    await client.refreshModels(false, { roots: ['/mnt/a/loras', '/mnt/b/loras'] });
+
+    const [url] = global.fetch.mock.calls[0];
+    expect(url.searchParams.getAll('roots')).toEqual(['/mnt/a/loras', '/mnt/b/loras']);
+    expect(url.searchParams.get('full_rebuild')).toBe('false');
+  });
+
+  it('reports the scoped scan summary and the entries kept unreachable', async () => {
+    const fetchControl = mockFetchPending();
+    const client = await createClient();
+    const { promise } = await startRefresh(client, false, { roots: ['/mnt/a/loras'] });
+
+    fetchControl.resolveOk({
+      status: 'success',
+      scanned_roots: ['a/loras'],
+      added: 2,
+      removed: 1,
+      kept_unreachable: 5,
+      unavailable_paths: [
+        { path: '/mnt/g/loras', reason: 'root_unreachable', kept: 5 },
+      ],
+      skipped_roots: [{ path: '/mnt/g/loras', label: 'g/loras' }],
+    });
+    await promise;
+
+    expect(showToastMock).toHaveBeenCalledWith(
+      'toast.api.refreshCompleteScoped',
+      { scope: 'a/loras', added: 2, removed: 1 },
+      'success'
+    );
+    expect(showToastMock).toHaveBeenCalledWith(
+      'toast.api.refreshKeptUnreachable',
+      { count: '5', paths: 'g/loras' },
+      'info'
+    );
+  });
+
+  it('keeps the generic completion toast for a full-library scan', async () => {
+    const fetchControl = mockFetchPending();
+    const client = await createClient();
+    const { promise } = await startRefresh(client);
+
+    fetchControl.resolveOk({
+      status: 'success',
+      scanned_roots: ['a/loras', 'b/loras'],
+      added: 0,
+      removed: 0,
+    });
+    await promise;
+
+    expect(showToastMock).toHaveBeenCalledWith(
+      'toast.api.refreshComplete',
+      { action: 'Refresh' },
+      'success'
+    );
+    expect(showToastMock).not.toHaveBeenCalledWith(
+      'toast.api.refreshCompleteScoped',
+      expect.anything(),
+      expect.anything()
+    );
+  });
+
   it('shows the cancelled toast when the server reports cancellation', async () => {
     const fetchControl = mockFetchPending();
     const client = await createClient();

tests/frontend/components/controls/pageControls.scanScope.test.js

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'fs';
+import path from 'path';
+
+const {
+  PAGE_CONTROLS_MODULE,
+  STATE_MODULE,
+  STORAGE_MODULE,
+  UI_HELPERS_MODULE,
+  EVENT_MANAGER_MODULE,
+  UPDATE_CHECK_MODULE,
+  SIDEBAR_MODULE,
+  SORT_DROPDOWN_MODULE,
+  API_FACTORY_MODULE,
+  I18N_MODULE,
+} = vi.hoisted(() => ({
+  PAGE_CONTROLS_MODULE: new URL('../../../../static/js/components/controls/PageControls.js', import.meta.url).pathname,
+  STATE_MODULE: new URL('../../../../static/js/state/index.js', import.meta.url).pathname,
+  STORAGE_MODULE: new URL('../../../../static/js/utils/storageHelpers.js', import.meta.url).pathname,
+  UI_HELPERS_MODULE: new URL('../../../../static/js/utils/uiHelpers.js', import.meta.url).pathname,
+  EVENT_MANAGER_MODULE: new URL('../../../../static/js/utils/EventManager.js', import.meta.url).pathname,
+  UPDATE_CHECK_MODULE: new URL('../../../../static/js/utils/updateCheckHelpers.js', import.meta.url).pathname,
+  SIDEBAR_MODULE: new URL('../../../../static/js/components/SidebarManager.js', import.meta.url).pathname,
+  SORT_DROPDOWN_MODULE: new URL('../../../../static/js/components/controls/SortDropdown.js', import.meta.url).pathname,
+  API_FACTORY_MODULE: new URL('../../../../static/js/api/modelApiFactory.js', import.meta.url).pathname,
+  I18N_MODULE: new URL('../../../../static/js/utils/i18nHelpers.js', import.meta.url).pathname,
+}));
+
+const CONTROLS_TEMPLATE = path.resolve(
+  __dirname,
+  '../../../../templates/components/controls.html'
+);
+
+const showToastMock = vi.fn();
+const modelClient = {
+  fetchModelRoots: vi.fn(),
+  refreshModels: vi.fn(),
+};
+
+vi.mock(STATE_MODULE, () => ({
+  state: {},
+  getCurrentPageState: vi.fn(() => ({ filters: {} })),
+  setCurrentPageType: vi.fn(),
+}));
+
+vi.mock(STORAGE_MODULE, () => ({
+  getStorageItem: vi.fn(),
+  setStorageItem: vi.fn(),
+  removeStorageItem: vi.fn(),
+  getSessionItem: vi.fn(),
+  setSessionItem: vi.fn(),
+  removeSessionItem: vi.fn(),
+}));
+
+vi.mock(UI_HELPERS_MODULE, () => ({
+  showToast: showToastMock,
+  openCivitaiByMetadata: vi.fn(),
+  isTypingContext: vi.fn(() => false),
+}));
+
+vi.mock(EVENT_MANAGER_MODULE, () => ({
+  eventManager: { on: vi.fn(), off: vi.fn(), emit: vi.fn() },
+}));
+
+vi.mock(UPDATE_CHECK_MODULE, () => ({
+  performModelUpdateCheck: vi.fn(),
+}));
+
+vi.mock(SIDEBAR_MODULE, () => ({
+  sidebarManager: {
+    setHostPageControls: vi.fn(),
+    initialize: vi.fn(async () => {}),
+    refresh: vi.fn(async () => {}),
+  },
+}));
+
+vi.mock(SORT_DROPDOWN_MODULE, () => ({
+  initSortDropdown: vi.fn(),
+  applySortToSelect: vi.fn(),
+  randomizeSortValue: vi.fn(),
+}));
+
+vi.mock(API_FACTORY_MODULE, () => ({
+  getModelApiClient: () => modelClient,
+}));
+
+vi.mock(I18N_MODULE, () => ({
+  translate: vi.fn((key, params, fallback) => {
+    if (!fallback) {
+      return key;
+    }
+    return Object.entries(params || {}).reduce(
+      (text, [name, value]) => text.replaceAll(`{${name}}`, value),
+      fallback
+    );
+  }),
+}));
+
+const { PageControls } = await import(PAGE_CONTROLS_MODULE);
+
+const ROOT_DETAILS = [
+  { path: '/mnt/a/loras', label: 'a/loras', reachable: true, models: 12 },
+  { path: '/mnt/b/loras', label: 'b/loras', reachable: false, models: 3 },
+];
+
+function buildControlsDom() {
+  document.body.innerHTML = `
+    <div class="dropdown-group">
+      <button data-action="refresh" class="dropdown-main"></button>
+      <button class="dropdown-toggle"></button>
+      <div class="dropdown-menu">
+        <div class="dropdown-item" data-action="full-rebuild"></div>
+        <div class="dropdown-separator"></div>
+        <div class="dropdown-section-title">Scan one folder</div>
+        <div id="refreshScopeMenu" class="dropdown-scope-list"></div>
+      </div>
+    </div>`;
+}
+
+function bareControls(api = {}) {
+  const controls = Object.create(PageControls.prototype);
+  controls.pageType = 'loras';
+  controls.api = api;
+  controls._scanScopeDetails = null;
+  controls._scanScopeLoading = false;
+  controls.refreshModels = vi.fn();
+  controls.sidebarManager = {
+    setHostPageControls: vi.fn(),
+    initialize: vi.fn(async () => {}),
+  };
+  return controls;
+}
+
+describe('PageControls refresh scope menu', () => {
+  beforeEach(() => {
+    showToastMock.mockReset();
+    modelClient.fetchModelRoots.mockReset();
+    modelClient.refreshModels.mockReset();
+    modelClient.fetchModelRoots.mockResolvedValue({ root_details: ROOT_DETAILS });
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('keeps the scope container in the controls template (non-recipes pages)', () => {
+    const html = readFileSync(CONTROLS_TEMPLATE, 'utf-8');
+    const rebuildIndex = html.indexOf('data-action="full-rebuild"');
+    const scopeIndex = html.indexOf('id="refreshScopeMenu"');
+
+    expect(rebuildIndex).toBeGreaterThan(-1);
+    // Same dropdown, after the rebuild entry.
+    expect(scopeIndex).toBeGreaterThan(rebuildIndex);
+    expect(html).toContain('loras.controls.refresh.scopeSection');
+    // The recipes page has no model roots, so the section is gated.
+    expect(html.slice(rebuildIndex, scopeIndex)).toContain("{% if page_id != 'recipes' %}");
+  });
+
+  it('registers the scan-scope API for every page through registerAPI', async () => {
+    const controls = bareControls();
+    controls.registerAPI({});
+
+    expect(typeof controls.api.fetchModelRoots).toBe('function');
+    expect(typeof controls.api.refreshModels).toBe('function');
+
+    await controls.api.fetchModelRoots();
+    expect(modelClient.fetchModelRoots).toHaveBeenCalled();
+
+    // The page facades used to drop the second argument, which silently turned
+    // a scoped scan into a full refresh.
+    await controls.api.refreshModels(false, { roots: ['/mnt/a/loras'] });
+    expect(modelClient.refreshModels).toHaveBeenCalledWith(false, { roots: ['/mnt/a/loras'] });
+  });
+
+  it('renders the root rows when the dropdown is opened', async () => {
+    buildControlsDom();
+    const controls = bareControls({
+      fetchModelRoots: vi.fn(async () => ({ root_details: ROOT_DETAILS })),
+      refreshModels: vi.fn(),
+    });
+
+    controls.initDropdowns();
+    document.querySelector('.dropdown-toggle').click();
+
+    await vi.waitFor(() => {
+      expect(document.querySelectorAll('.scan-root-item').length).toBe(2);
+    });
+    expect(document.querySelector('.scan-root-item').dataset.root).toBe('/mnt/a/loras');
+    expect(document.querySelector('.scan-root-count').textContent).toBe('12 models');
+    expect(document.querySelectorAll('.scan-root-item')[1].classList.contains('is-offline')).toBe(true);
+  });
+
+  it('scans the clicked root only', async () => {
+    buildControlsDom();
+    const controls = bareControls({
+      fetchModelRoots: vi.fn(async () => ({ root_details: ROOT_DETAILS })),
+      refreshModels: vi.fn(),
+    });
+
+    controls.initDropdowns();
+    document.querySelector('.dropdown-toggle').click();
+    await vi.waitFor(() => {
+      expect(document.querySelectorAll('.scan-root-item').length).toBe(2);
+    });
+
+    document.querySelectorAll('.scan-root-item')[0].click();
+
+    expect(controls.refreshModels).toHaveBeenCalledWith(false, { roots: ['/mnt/a/loras'] });
+    expect(showToastMock).not.toHaveBeenCalled();
+  });
+
+  it('explains an offline root instead of scanning it', async () => {
+    buildControlsDom();
+    const controls = bareControls({
+      fetchModelRoots: vi.fn(async () => ({ root_details: ROOT_DETAILS })),
+      refreshModels: vi.fn(),
+    });
+
+    controls.initDropdowns();
+    document.querySelector('.dropdown-toggle').click();
+    await vi.waitFor(() => {
+      expect(document.querySelectorAll('.scan-root-item').length).toBe(2);
+    });
+
+    document.querySelectorAll('.scan-root-item')[1].click();
+
+    expect(controls.refreshModels).not.toHaveBeenCalled();
+    // Exactly three arguments: key, params, type. A 4th "fallback" argument
+    // pushed the sentence into the type slot and rendered an unstyled toast.
+    expect(showToastMock).toHaveBeenCalledWith(
+      'toast.api.scanRootUnreachable',
+      { scope: 'b/loras' },
+      'info'
+    );
+  });
+});

tests/frontend/components/controls/scanScopeMenu.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { I18N_MODULE, MODULE } = vi.hoisted(() => ({
+  I18N_MODULE: new URL('../../../../static/js/utils/i18nHelpers.js', import.meta.url).pathname,
+  MODULE: new URL('../../../../static/js/components/controls/ScanScopeMenu.js', import.meta.url).pathname,
+}));
+
+vi.mock(I18N_MODULE, () => ({
+  translate: vi.fn((key, params, fallback) => {
+    if (!fallback) {
+      return key;
+    }
+    return Object.entries(params || {}).reduce(
+      (text, [name, value]) => text.replaceAll(`{${name}}`, value),
+      fallback
+    );
+  }),
+}));
+
+const { renderScanScopeMenu, resolveScanScopeTarget } = await import(MODULE);
+
+describe('ScanScopeMenu', () => {
+  let menu;
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="refreshScopeMenu"></div>';
+    menu = document.getElementById('refreshScopeMenu');
+  });
+
+  it('renders one row per root with label, count and offline state', () => {
+    renderScanScopeMenu(menu, [
+      { path: '/mnt/a/loras', label: 'a/loras', reachable: true, models: 7 },
+      { path: '/mnt/b/loras', label: 'b/loras', reachable: false, models: 0 },
+    ]);
+
+    const rows = menu.querySelectorAll('.scan-root-item');
+    expect(rows.length).toBe(2);
+
+    expect(rows[0].dataset.action).toBe('scan-root');
+    expect(rows[0].dataset.root).toBe('/mnt/a/loras');
+    expect(rows[0].title).toBe('/mnt/a/loras');
+    expect(rows[0].querySelector('.scan-root-label').textContent).toBe('a/loras');
+    expect(rows[0].querySelector('.scan-root-count').textContent).toBe('7 models');
+    expect(rows[0].classList.contains('is-offline')).toBe(false);
+
+    expect(rows[1].classList.contains('is-offline')).toBe(true);
+    expect(rows[1].querySelector('.scan-root-offline').textContent).toBe('Offline');
+    // Offline rows stay clickable so the click can explain the state.
+    expect(rows[1].dataset.action).toBe('scan-root');
+  });
+
+  it('resolveScanScopeTarget reads path, label and offline state', () => {
+    renderScanScopeMenu(menu, [
+      { path: '/mnt/b/loras', label: 'b/loras', reachable: false, models: 0 },
+    ]);
+
+    expect(resolveScanScopeTarget(menu.querySelector('.scan-root-item'))).toEqual({
+      rootPath: '/mnt/b/loras',
+      label: 'b/loras',
+      offline: true,
+    });
+  });
+
+  it('skips malformed entries and replaces the previous list', () => {
+    renderScanScopeMenu(menu, [{ path: '/mnt/a' }, null, {}]);
+    expect(menu.querySelectorAll('.scan-root-item').length).toBe(1);
+
+    renderScanScopeMenu(menu, []);
+    expect(menu.querySelectorAll('.scan-root-item').length).toBe(0);
+  });
+
+  it('falls back to the path when a root has no label', () => {
+    renderScanScopeMenu(menu, [{ path: '/mnt/a/loras', reachable: true, models: 0 }]);
+
+    expect(menu.querySelector('.scan-root-label').textContent).toBe('/mnt/a/loras');
+  });
+});

tests/frontend/utils/toastTypes.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { UI_HELPERS_MODULE, I18N_MODULE } = vi.hoisted(() => ({
+  UI_HELPERS_MODULE: new URL('../../../static/js/utils/uiHelpers.js', import.meta.url).pathname,
+  I18N_MODULE: new URL('../../../static/js/utils/i18nHelpers.js', import.meta.url).pathname,
+}));
+
+vi.mock(I18N_MODULE, () => ({
+  translate: vi.fn((key, params, fallback) => fallback || key),
+}));
+
+const { showToast } = await import(UI_HELPERS_MODULE);
+
+describe('toast type styling', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('applies the requested type class', () => {
+    showToast('plain message', {}, 'success');
+    expect(document.querySelector('.toast').className).toBe('toast toast-success');
+  });
+
+  it('coerces an unknown type to info instead of rendering an unstyled toast', () => {
+    // Regression guard: a call site that passed its fallback sentence as the
+    // `type` produced `toast toast-drive-Z is not reachable ...`, which matched
+    // no rule at all (no icon, no accent border).
+    showToast('plain message', {}, 'drive-Z is not reachable right now');
+    expect(document.querySelector('.toast').className).toBe('toast toast-info');
+  });
+
+  it('defaults to info when no type is given', () => {
+    showToast('plain message');
+    expect(document.querySelector('.toast').className).toBe('toast toast-info');
+  });
+});