feat(ui): show live scan progress and ETA for cache refresh

Broadcast typed scan_progress messages over /ws/fetch-progress from the
manual refresh/rebuild paths of ModelScanner and RecipeScanner, and
render percent, processed/total, current file name and an EMA-smoothed
ETA in the loading overlay. Hardcoded refresh strings move to i18n
(common.scanProgress); WS connection failure falls back to the previous
static loading behavior.

static/js/api/baseModelApi.js

@@ -12,6 +12,11 @@ import {
 } from './apiConfig.js';
 import { resetAndReload } from './modelApiFactory.js';
 import { sidebarManager } from '../components/SidebarManager.js';
+// Shared scan ETA helpers live in a dependency-light module so pages that do
+// not use BaseModelApiClient (e.g. recipes) can reuse them without pulling
+// this module's import cycle (modelApiFactory -> loraApi -> baseModelApi).
+import { createScanEtaTracker, formatScanRemainingTime } from '../utils/scanEtaUtils.js';
+export { createScanEtaTracker, formatScanRemainingTime };
 
 /**
  * Abstract base class for all model API clients
@@ -507,23 +512,67 @@ export class BaseModelApiClient {
 
     async refreshModels(fullRebuild = false) {
         const abortController = new AbortController();
-        try {
-            state.loadingManager.show(
-                `${fullRebuild ? 'Full rebuild' : 'Refreshing'} ${this.apiConfig.config.displayName}s...`,
-                0
+        const displayName = this.apiConfig.config.displayName;
+        const singularName = this.apiConfig.config.singularName;
+        const actionText = translate(
+            fullRebuild ? 'common.scanProgress.actionFullRebuild' : 'common.scanProgress.actionRefresh',
+            {},
+            fullRebuild ? 'Full rebuild' : 'Refresh'
+        );
+        const actionLowerText = translate(
+            fullRebuild ? 'common.scanProgress.actionRebuildLower' : 'common.scanProgress.actionRefreshLower',
+            {},
+            fullRebuild ? 'rebuild' : 'refresh'
+        );
+        const initialMessage = translate(
+            fullRebuild ? 'common.scanProgress.fullRebuilding' : 'common.scanProgress.refreshing',
+            { type: displayName },
+            `${fullRebuild ? 'Full rebuild' : 'Refreshing'} ${displayName}s...`
+        );
+        const etaTracker = createScanEtaTracker();
+        let ws = null;
+
+        const handleScanProgress = (data) => {
+            if (typeof data.progress === 'number') {
+                state.loadingManager.setProgress(data.progress);
+            }
+            let statusText = translate(
+                `common.scanProgress.stages.${data.stage}`,
+                { total: data.total },
+                data.stage || ''
             );
+            if (data.status === 'processing' && data.total > 0) {
+                statusText += ` (${data.processed}/${data.total})`;
+                if (data.current_name) {
+                    statusText += ` ${data.current_name}`;
+                }
+                const etaText = etaTracker.update(data.processed, data.total);
+                if (etaText) {
+                    statusText += ` | ${etaText}`;
+                }
+            }
+            state.loadingManager.setStatus(statusText);
+        };
+
+        try {
+            state.loadingManager.show(initialMessage, 0);
             state.loadingManager.showCancelButton(() => {
                 this.cancelTask();
                 abortController.abort();
             });
 
+            // Connect to the shared progress channel for live scan updates.
+            // Failure to connect must not block the refresh itself — fall back
+            // to the plain loading indicator.
+            ws = await this._connectScanProgressSocket(handleScanProgress, singularName);
+
             const url = new URL(this.apiConfig.endpoints.scan, window.location.origin);
             url.searchParams.append('full_rebuild', fullRebuild);
 
             const response = await fetch(url, { signal: abortController.signal });
 
             if (!response.ok) {
-                throw new Error(`Failed to refresh ${this.apiConfig.config.displayName}s: ${response.status} ${response.statusText}`);
+                throw new Error(`Failed to refresh ${displayName}s: ${response.status} ${response.statusText}`);
             }
 
             const data = await response.json();
@@ -534,20 +583,69 @@ export class BaseModelApiClient {
 
             resetAndReload(true);
 
-            showToast('toast.api.refreshComplete', { action: fullRebuild ? 'Full rebuild' : 'Refresh' }, 'success');
+            showToast('toast.api.refreshComplete', { action: actionText }, 'success');
         } catch (error) {
             if (error.name === 'AbortError') {
                 showToast('toast.api.operationCancelled', {}, 'info');
                 return;
             }
             console.error('Refresh failed:', error);
-            showToast('toast.api.refreshFailed', { action: fullRebuild ? 'rebuild' : 'refresh', type: this.apiConfig.config.displayName }, 'error');
+            showToast('toast.api.refreshFailed', { action: actionLowerText, type: displayName }, 'error');
         } finally {
+            if (ws) {
+                ws.close();
+            }
             state.loadingManager.hide();
             state.loadingManager.restoreProgressBar();
         }
     }
 
+    /**
+     * Connect to the shared fetch-progress WebSocket for scan progress updates.
+     * Returns null when the connection cannot be established (silent fallback).
+     * @param {Function} onScanProgress - Handler for scan_progress messages
+     * @param {string} singularName - Model type filter (e.g. 'lora')
+     * @returns {Promise<WebSocket|null>}
+     */
+    async _connectScanProgressSocket(onScanProgress, singularName) {
+        let socket = null;
+        try {
+            const wsProtocol = window.location.protocol === 'https:' ? 'wss://' : 'ws://';
+            socket = new WebSocket(`${wsProtocol}${window.location.host}${WS_ENDPOINTS.fetchProgress}`);
+
+            await new Promise((resolve, reject) => {
+                socket.onopen = resolve;
+                socket.onerror = reject;
+            });
+
+            socket.onmessage = (event) => {
+                let data;
+                try {
+                    data = JSON.parse(event.data);
+                } catch (parseError) {
+                    return;
+                }
+                // Only handle scan progress for this client's model type;
+                // other operations share this channel and must be ignored.
+                if (data.type !== 'scan_progress' || data.model_type !== singularName) {
+                    return;
+                }
+                onScanProgress(data);
+            };
+
+            return socket;
+        } catch (error) {
+            if (socket) {
+                try {
+                    socket.close();
+                } catch (closeError) {
+                    // Ignore close errors during fallback
+                }
+            }
+            return null;
+        }
+    }
+
     async refreshSingleModelMetadata(filePath) {
         try {
             state.loadingManager.showSimpleLoading('Refreshing metadata...');
@@ -605,6 +703,9 @@ export class BaseModelApiClient {
                     ws.onmessage = (event) => {
                         const data = JSON.parse(event.data);
 
+                        // Scan progress shares this channel; it is handled by refreshModels
+                        if (data.type === 'scan_progress') return;
+
                         switch (data.status) {
                             case 'started':
                                 loading.setStatus('Starting metadata fetch...');

static/js/api/recipeApi.js

@@ -1,7 +1,12 @@
 import { RecipeCard } from '../components/RecipeCard.js';
 import { state, getCurrentPageState } from '../state/index.js';
 import { showToast } from '../utils/uiHelpers.js';
+import { translate } from '../utils/i18nHelpers.js';
 import { captureScrollPosition, restoreScrollPosition } from '../utils/infiniteScroll.js';
+import { WS_ENDPOINTS } from './apiConfig.js';
+// Import from the dependency-light utils module, not baseModelApi.js, to
+// avoid the baseModelApi <-> modelApiFactory import cycle on this page.
+import { createScanEtaTracker } from '../utils/scanEtaUtils.js';
 
 const RECIPE_ENDPOINTS = {
     list: '/api/lm/recipes',
@@ -333,11 +338,53 @@ export async function syncChanges() {
 }
 
 export async function refreshRecipes(fullRebuild = true) {
-    const actionLabel = fullRebuild ? 'Rebuilding recipe cache' : 'Refreshing recipes';
-    const actionToast = fullRebuild ? 'Full rebuild' : 'Refresh';
+    const actionText = translate(
+        fullRebuild ? 'common.scanProgress.actionFullRebuild' : 'common.scanProgress.actionRefresh',
+        {},
+        fullRebuild ? 'Full rebuild' : 'Refresh'
+    );
+    const actionLowerText = translate(
+        fullRebuild ? 'common.scanProgress.actionRebuildLower' : 'common.scanProgress.actionRefreshLower',
+        {},
+        fullRebuild ? 'rebuild' : 'refresh'
+    );
+    const initialMessage = translate(
+        fullRebuild ? 'common.scanProgress.fullRebuilding' : 'common.scanProgress.refreshing',
+        { type: RECIPE_SIDEBAR_CONFIG.config.displayName },
+        `${fullRebuild ? 'Full rebuild' : 'Refreshing'} Recipes...`
+    );
+    const etaTracker = createScanEtaTracker();
+    let ws = null;
+
+    const handleScanProgress = (data) => {
+        if (typeof data.progress === 'number') {
+            state.loadingManager.setProgress(data.progress);
+        }
+        let statusText = translate(
+            `common.scanProgress.stages.${data.stage}`,
+            { total: data.total },
+            data.stage || ''
+        );
+        if (data.status === 'processing' && data.total > 0) {
+            statusText += ` (${data.processed}/${data.total})`;
+            if (data.current_name) {
+                statusText += ` ${data.current_name}`;
+            }
+            const etaText = etaTracker.update(data.processed, data.total);
+            if (etaText) {
+                statusText += ` | ${etaText}`;
+            }
+        }
+        state.loadingManager.setStatus(statusText);
+    };
 
     try {
-        state.loadingManager.show(`${actionLabel}...`, 0);
+        state.loadingManager.show(initialMessage, 0);
+
+        // Connect to the shared progress channel for live scan updates.
+        // Failure to connect must not block the refresh itself — fall back
+        // to the plain loading indicator.
+        ws = await connectScanProgressSocket(handleScanProgress);
 
         const url = new URL(RECIPE_ENDPOINTS.scan, window.location.origin);
         url.searchParams.append('full_rebuild', fullRebuild);
@@ -356,16 +403,64 @@ export async function refreshRecipes(fullRebuild = true) {
 
         await resetAndReload(false);
 
-        showToast('toast.api.refreshComplete', { action: actionToast }, 'success');
+        showToast('toast.api.refreshComplete', { action: actionText }, 'success');
     } catch (error) {
         console.error('Error refreshing recipes:', error);
-        showToast('toast.api.refreshFailed', { action: fullRebuild ? 'rebuild' : 'refresh', type: 'recipe' }, 'error');
+        showToast('toast.api.refreshFailed', { action: actionLowerText, type: 'recipe' }, 'error');
     } finally {
+        if (ws) {
+            ws.close();
+        }
         state.loadingManager.hide();
         state.loadingManager.restoreProgressBar();
     }
 }
 
+/**
+ * Connect to the shared fetch-progress WebSocket for recipe scan progress.
+ * Returns null when the connection cannot be established (silent fallback).
+ * @param {Function} onScanProgress - Handler for scan_progress messages
+ * @returns {Promise<WebSocket|null>}
+ */
+async function connectScanProgressSocket(onScanProgress) {
+    let socket = null;
+    try {
+        const wsProtocol = window.location.protocol === 'https:' ? 'wss://' : 'ws://';
+        socket = new WebSocket(`${wsProtocol}${window.location.host}${WS_ENDPOINTS.fetchProgress}`);
+
+        await new Promise((resolve, reject) => {
+            socket.onopen = resolve;
+            socket.onerror = reject;
+        });
+
+        socket.onmessage = (event) => {
+            let data;
+            try {
+                data = JSON.parse(event.data);
+            } catch (parseError) {
+                return;
+            }
+            // Only handle recipe scan progress; other operations share this
+            // channel and must be ignored.
+            if (data.type !== 'scan_progress' || data.model_type !== 'recipe') {
+                return;
+            }
+            onScanProgress(data);
+        };
+
+        return socket;
+    } catch (error) {
+        if (socket) {
+            try {
+                socket.close();
+            } catch (closeError) {
+                // Ignore close errors during fallback
+            }
+        }
+        return null;
+    }
+}
+
 /**
  * Load more recipes with pagination - updated to work with VirtualScroller
  * @param {boolean} resetPage - Whether to reset to the first page

static/js/utils/scanEtaUtils.js

@@ -0,0 +1,61 @@
+import { translate } from './i18nHelpers.js';
+
+/**
+ * Format a remaining-time estimate for scan progress display.
+ * @param {number} remainingMs - Estimated remaining time in milliseconds
+ * @returns {string} Localized ETA text
+ */
+export function formatScanRemainingTime(remainingMs) {
+    if (remainingMs < 60000) {
+        return translate('common.scanProgress.eta.lessThanMinute', {}, 'Less than a minute remaining');
+    }
+    if (remainingMs < 3600000) {
+        const minutes = Math.round(remainingMs / 60000);
+        return translate('common.scanProgress.eta.minutes', { minutes }, `~${minutes} min remaining`);
+    }
+    const hours = Math.floor(remainingMs / 3600000);
+    const minutes = Math.round((remainingMs % 3600000) / 60000);
+    return translate('common.scanProgress.eta.hours', { hours, minutes }, `~${hours} hr ${minutes} min remaining`);
+}
+
+/**
+ * Create an ETA tracker for scan progress. Uses an exponential moving
+ * average (0.7/0.3) over the observed per-file processing time, mirroring
+ * the estimator in components/initialization.js.
+ * @returns {{ update: (processed: number, total: number) => (string|null) }}
+ */
+export function createScanEtaTracker() {
+    let startTime = null;
+    let lastProcessed = 0;
+    let averageMsPerFile = null;
+
+    return {
+        /**
+         * Update with the latest counters.
+         * @returns {string|null} Localized ETA text, or null when not applicable
+         */
+        update(processed, total) {
+            if (!total || total <= 0 || processed >= total) {
+                return null;
+            }
+            const now = Date.now();
+            if (startTime === null) {
+                // First sample only anchors the timer; not enough data yet
+                startTime = now;
+                lastProcessed = processed;
+                return translate('initialization.estimatingTime', {}, 'Estimating time...');
+            }
+            if (processed > lastProcessed) {
+                const msPerFile = (now - startTime) / processed;
+                averageMsPerFile = averageMsPerFile === null
+                    ? msPerFile
+                    : averageMsPerFile * 0.7 + msPerFile * 0.3;
+                lastProcessed = processed;
+            }
+            if (averageMsPerFile === null) {
+                return translate('initialization.estimatingTime', {}, 'Estimating time...');
+            }
+            return formatScanRemainingTime((total - lastProcessed) * averageMsPerFile);
+        }
+    };
+}