feat: add recoverable import previews

Author: SysAdminDoc

CHANGELOG.md

@@ -15,6 +15,7 @@ All notable changes to ScriptHunt will be documented in this file.
 - Reconciled package and lockfile version metadata, pinned the verified Playwright release, and expanded version drift tests to cover both lockfile version fields and the dependency pin.
 - Replaced implied trust for unscanned/unavailable evidence with explicit Unknown, stale-evidence, and dependency-unverified labels, with inspectable scan URL, timestamp, status, hash, and cache age.
 - Added optional bounded-concurrency, non-executing HTTPS integrity checks for `@require` and `@resource` dependencies, including canonical provenance, pinning state, declared hash verification, failures, content changes, and parent-scan caching.
+- Added installed/favorite import previews with valid, invalid, duplicate, conflict, and manager-format counts; merge, replace, skip-conflict, and cancel actions; and versioned pre-import snapshots with one-click rollback.
 
 ## [v0.5.1]
 

README.md

@@ -56,9 +56,9 @@ npm run qa
 | **Dependency Integrity** | Optional, non-executing HTTPS checks for up to 12 `@require`/`@resource` URLs with 1 MB/7 second limits, pinned/floating provenance, declared hash verification, change detection, and cached evidence |
 | **Permission Risk Pills** | Color-coded pills showing @grant danger levels (safe/warn/danger) per script |
 | **Script Comparison** | Select up to 3 scripts for side-by-side comparison with best-value highlighting |
-| **Favorites** | Save scripts to localStorage with versioned JSON export/import and undo on removal |
+| **Favorites** | Save scripts locally with versioned JSON export/import, conflict preview, recovery snapshots, and undo |
 | **Saved Searches** | Save query/filter/source combinations locally and manually refresh them to badge new or updated results |
-| **Installed Import/Export** | Import and export installed-script lists locally to mark installed scripts and available updates in search results |
+| **Installed Import/Export** | Preview manager/app backups before merge, replace, or conflict-skip; every write creates a versioned local snapshot with one-click rollback |
 | **Advanced Query Syntax** | `site:`, `author:`, `updated:`, `grant:` operators with domain-aware by-site.json search and metadata-backed grant filtering |
 | **Advanced Filters** | Visible controls for source, license, installs, updated date, catalog language, @grant, risk, and applies-to domain |
 | **Applies-To Evidence** | Site-filtered results show source site matches alongside parsed `@match`, `@include`, and `@exclude` metadata evidence |
@@ -234,7 +234,7 @@ Yes. Deploy the included Cloudflare Worker template (free tier: 100K requests/da
 - **CORS Proxy** — optional custom route followed by an opt-out public allorigins.win → codetabs → everyorigin fallback chain with explicit target-URL disclosure
 - **PWA** — manifest.json + service worker for installability, explicit update prompts, offline shell fallback notices, and local recent-search recovery
 - **localStorage + IndexedDB** - preferences, favorites, source toggles, theme, recent search results, and scan cache persist locally; diagnostics can clear recoverable caches without deleting user records; no tracking, no cookies, no server-side state
-- **Versioned JSON payloads** - favorites and installed-list exports use schema v1; imports validate URLs, report skipped invalid rows, and still accept manager-style `scripts` arrays plus legacy arrays
+- **Versioned JSON payloads** - favorites and installed-list exports use schema v1; imports validate URLs, preview invalid/duplicate/conflict counts and manager provenance, then snapshot both local lists before mutation for rollback
 - **Local QA** - `npm run qa` runs npm audit, Worker tests, version/source-documentation drift checks, and browser tests against the repo-local static server; Playwright is pinned to the exact locally verified release
 
 ---

index.html

@@ -1248,6 +1248,116 @@ <h3>Search userscripts everywhere</h3>
         return { type: type, items: items, invalid: invalid, managerFormat: managerFormat };
     }
 
+    function importRecordsEqual(a, b) {
+        return JSON.stringify(exportScriptRecord(a)) === JSON.stringify(exportScriptRecord(b));
+    }
+
+    function buildImportPreview(parsed) {
+        var existing = parsed.type === 'installed' ? getInstalledScripts() : getFavs();
+        var existingByKey = {};
+        existing.forEach(function(item) { existingByKey[scriptRecordKey(item)] = item; });
+        var incomingByKey = {}, duplicateRows = 0;
+        parsed.items.forEach(function(item) {
+            var key = scriptRecordKey(item);
+            if (incomingByKey[key]) duplicateRows++;
+            incomingByKey[key] = item;
+        });
+        var incoming = Object.keys(incomingByKey).map(function(key) { return incomingByKey[key]; });
+        var conflicts = 0, duplicates = duplicateRows, additions = 0;
+        incoming.forEach(function(item) {
+            var current = existingByKey[scriptRecordKey(item)];
+            if (!current) additions++;
+            else if (importRecordsEqual(current, item)) duplicates++;
+            else conflicts++;
+        });
+        return {
+            type: parsed.type,
+            items: incoming,
+            existing: existing,
+            valid: parsed.items.length,
+            invalid: parsed.invalid,
+            duplicates: duplicates,
+            conflicts: conflicts,
+            additions: additions,
+            managerFormat: parsed.managerFormat,
+        };
+    }
+
+    function saveImportSnapshot(type) {
+        var snapshot = {
+            schema: 'scripthunt-import-snapshot',
+            version: 1,
+            createdAt: new Date().toISOString(),
+            importType: type,
+            favorites: getFavs(),
+            installed: getInstalledScripts(),
+        };
+        localStorage.setItem('sh_import_snapshot', JSON.stringify(snapshot));
+        return snapshot;
+    }
+
+    function restoreImportSnapshot(snapshot) {
+        if (!snapshot || snapshot.schema !== 'scripthunt-import-snapshot' || snapshot.version !== 1) return false;
+        setFavs(snapshot.favorites || []);
+        setInstalledScripts(snapshot.installed || []);
+        if (state.showFavs) showFavorites();
+        else if (state.results.length) sortAndRender();
+        return true;
+    }
+
+    function applyImportPreview(preview, mode) {
+        var snapshot = saveImportSnapshot(preview.type);
+        var existingByKey = {};
+        preview.existing.forEach(function(item) { existingByKey[scriptRecordKey(item)] = item; });
+        var next;
+        if (mode === 'replace') {
+            next = preview.items.slice();
+        } else {
+            next = preview.existing.slice();
+            preview.items.forEach(function(item) {
+                var key = scriptRecordKey(item);
+                var index = next.findIndex(function(current) { return scriptRecordKey(current) === key; });
+                if (index < 0) next.push(item);
+                else if (mode === 'merge') next[index] = item;
+            });
+        }
+        if (preview.type === 'installed') {
+            setInstalledScripts(next);
+            if (state.results.length) sortAndRender();
+        } else {
+            setFavs(next);
+            if (state.showFavs) showFavorites();
+        }
+        closeCompareModal();
+        var manager = preview.managerFormat ? '; manager backup detected' : '';
+        showToast('Imported ' + preview.items.length + ' ' + preview.type + ' records using ' + mode + manager, 'info', 8000, function() {
+            if (restoreImportSnapshot(snapshot)) showToast('Import rolled back', 'info', 2500);
+        });
+    }
+
+    function openImportPreview(preview) {
+        modalReturnFocus = document.activeElement;
+        var overlay = document.getElementById('modalOverlay');
+        var modal = document.getElementById('modalContent');
+        overlay.setAttribute('aria-label', 'Import preview');
+        modal.innerHTML = '<div class="modal-header"><h2 class="modal-title">Import Preview</h2><button class="modal-close" id="modalCloseBtn" aria-label="Cancel import">&times;</button></div>' +
+            '<div class="compare-grid" style="grid-template-columns:repeat(5,minmax(0,1fr))">' +
+            '<div class="compare-col"><h3>Valid</h3><div class="compare-value">' + preview.valid + '</div></div>' +
+            '<div class="compare-col"><h3>Invalid</h3><div class="compare-value">' + preview.invalid + '</div></div>' +
+            '<div class="compare-col"><h3>Duplicates</h3><div class="compare-value">' + preview.duplicates + '</div></div>' +
+            '<div class="compare-col"><h3>Conflicts</h3><div class="compare-value">' + preview.conflicts + '</div></div>' +
+            '<div class="compare-col"><h3>New</h3><div class="compare-value">' + preview.additions + '</div></div></div>' +
+            '<p class="bookmarklet-desc">Type: ' + esc(preview.type) + (preview.managerFormat ? '; manager backup: ' + esc(preview.managerFormat) : '') + '. Merge updates conflicts, replace discards the current list, and skip keeps current conflicting records.</p>' +
+            '<div class="diagnostics-actions"><button class="tool-btn" id="importCancel" type="button">Cancel</button><button class="tool-btn" id="importSkip" type="button">Skip conflicts</button><button class="tool-btn" id="importReplace" type="button">Replace</button><button class="tool-btn" id="importMerge" type="button">Merge</button></div>';
+        overlay.classList.add('visible');
+        document.getElementById('modalCloseBtn').addEventListener('click', closeCompareModal);
+        document.getElementById('importCancel').addEventListener('click', closeCompareModal);
+        document.getElementById('importSkip').addEventListener('click', function() { applyImportPreview(preview, 'skip'); });
+        document.getElementById('importReplace').addEventListener('click', function() { applyImportPreview(preview, 'replace'); });
+        document.getElementById('importMerge').addEventListener('click', function() { applyImportPreview(preview, 'merge'); });
+        document.getElementById('importMerge').focus();
+    }
+
     function renderProvenance(item, installed) {
         if (!installed || !installed.installed || !installed.record) return '';
         var rec = installed.record;
@@ -3098,6 +3208,7 @@ <h3>Search userscripts everywhere</h3>
     function closeCompareModal() {
         var overlay = document.getElementById('modalOverlay');
         overlay.classList.remove('visible');
+        overlay.setAttribute('aria-label', 'Script comparison detail');
         if (modalReturnFocus && document.contains(modalReturnFocus)) modalReturnFocus.focus();
         modalReturnFocus = null;
     }
@@ -3116,6 +3227,7 @@ <h3>Search userscripts everywhere</h3>
         var items = state.compareIds.map(function(id) { return state.results.find(function(r) { return r.id === id; }); }).filter(Boolean);
         if (items.length < 2) return;
         modalReturnFocus = document.activeElement;
+        document.getElementById('modalOverlay').setAttribute('aria-label', 'Script comparison detail');
         var modal = document.getElementById('modalContent');
         var colW = items.length === 2 ? '1fr 1fr' : '1fr 1fr 1fr';
         var h = '<div class="modal-header"><h2 class="modal-title">Script Comparison</h2><button class="modal-close" id="modalCloseBtn" aria-label="Close comparison">&times;</button></div>';
@@ -3998,22 +4110,7 @@ <h3>Search userscripts everywhere</h3>
         reader.onload = function(e) {
             try {
                 var parsed = parseScriptImportPayload(JSON.parse(e.target.result), importMode);
-                if (parsed.type === 'installed') {
-                    setInstalledScripts(parsed.items);
-                    if (state.results.length) sortAndRender();
-                    var importMsg = 'Imported ' + parsed.items.length + ' installed scripts' + (parsed.invalid ? ' (' + parsed.invalid + ' invalid skipped)' : '');
-                    if (parsed.managerFormat) importMsg += ' (detected manager backup)';
-                    showToast(importMsg, 'info', 3000);
-                    return;
-                }
-                var existing = getFavs(), ids = new Set(existing.map(scriptRecordKey));
-                var added = 0;
-                parsed.items.forEach(function(item) {
-                    var key = scriptRecordKey(item);
-                    if (key && !ids.has(key)) { existing.push(item); ids.add(key); added++; }
-                });
-                setFavs(existing); showFavorites();
-                showToast('Imported ' + added + ' new favorites (' + (parsed.items.length - added) + ' duplicates skipped' + (parsed.invalid ? ', ' + parsed.invalid + ' invalid skipped' : '') + ')', 'info', 3000);
+                openImportPreview(buildImportPreview(parsed));
             } catch(err) { showToast('Invalid import file', 'error', 3000); }
         };
         reader.readAsText(file); this.value = '';

tests/smoke.spec.js

@@ -315,7 +315,9 @@ test('installed import marks matching scripts and update state', async ({ page }
       }],
     })),
   });
-  await expect(page.locator('.toast').last()).toContainText('Imported 1 installed scripts');
+  await expect(page.getByRole('dialog', { name: 'Import preview' })).toContainText('Valid');
+  await page.click('#importReplace');
+  await expect(page.locator('.toast').last()).toContainText('Imported 1 installed records using replace');
 
   await runSearch(page);
   const card = page.locator('.result-card').filter({ hasText: 'YouTube Enhancer' });
@@ -359,7 +361,11 @@ test('script imports skip invalid rows without aborting valid rows', async ({ pa
     })),
   });
 
-  await expect(page.locator('.toast').last()).toContainText('Imported 1 installed scripts (2 invalid skipped)');
+  const preview = page.getByRole('dialog', { name: 'Import preview' });
+  await expect(preview).toContainText('Valid');
+  await expect(preview).toContainText('Invalid');
+  await page.click('#importReplace');
+  await expect(page.locator('.toast').last()).toContainText('Imported 1 installed records using replace');
   const stored = await page.evaluate(() => JSON.parse(localStorage.getItem('sh_installed_scripts')));
   expect(stored.schema).toBe('scripthunt-installed');
   expect(stored.version).toBe(1);
@@ -396,15 +402,86 @@ test('manager-style backup imports are recognized and normalized', async ({ page
     ])),
   });
 
-  await expect(page.locator('.toast').last()).toContainText('Imported 2 installed scripts');
-  await expect(page.locator('.toast').last()).toContainText('manager backup');
+  await expect(page.getByRole('dialog', { name: 'Import preview' })).toContainText('manager backup: manager-array');
+  await page.click('#importReplace');
+  await expect(page.locator('.toast').last()).toContainText('Imported 2 installed records using replace');
+  await expect(page.locator('.toast').last()).toContainText('manager backup detected');
 
   const stored = await page.evaluate(() => JSON.parse(localStorage.getItem('sh_installed_scripts')));
   expect(stored.installed).toHaveLength(2);
   expect(stored.installed[0].name).toBe('VM Exported Script');
   expect(stored.installed[0].installUrl).toBe('https://greasyfork.org/scripts/999/code.user.js');
 });
 
+test('import preview supports cancellation, conflict merge, snapshots, and rollback', async ({ page }) => {
+  await page.goto('/');
+  await page.evaluate(() => {
+    setInstalledScripts([{
+      name: 'Existing Script',
+      version: '1.0.0',
+      installUrl: 'https://example.com/existing.user.js',
+    }]);
+  });
+  const payload = {
+    schema: 'scripthunt-installed',
+    version: 1,
+    installed: [
+      { name: 'Existing Script', version: '2.0.0', installUrl: 'https://example.com/existing.user.js' },
+      { name: 'New Script', version: '1.0.0', installUrl: 'https://example.com/new.user.js' },
+      { name: 'New Script', version: '1.0.0', installUrl: 'https://example.com/new.user.js' },
+      { name: 'Invalid Script', installUrl: 'javascript:alert(1)' },
+    ],
+  };
+  const chooseImport = async () => {
+    const chooserPromise = page.waitForEvent('filechooser');
+    await page.click('#btnImportInstalled');
+    const chooser = await chooserPromise;
+    await chooser.setFiles({
+      name: 'preview.json',
+      mimeType: 'application/json',
+      buffer: Buffer.from(JSON.stringify(payload)),
+    });
+  };
+
+  await chooseImport();
+  const preview = page.getByRole('dialog', { name: 'Import preview' });
+  const counts = preview.locator('.compare-col');
+  await expect(counts.nth(0)).toContainText('Valid3');
+  await expect(counts.nth(1)).toContainText('Invalid1');
+  await expect(counts.nth(2)).toContainText('Duplicates1');
+  await expect(counts.nth(3)).toContainText('Conflicts1');
+  await expect(counts.nth(4)).toContainText('New1');
+  await page.click('#importCancel');
+  expect(await page.evaluate(() => getInstalledScripts().map((item) => item.version))).toEqual(['1.0.0']);
+  expect(await page.evaluate(() => localStorage.getItem('sh_import_snapshot'))).toBeNull();
+
+  await chooseImport();
+  await page.click('#importMerge');
+  const merged = await page.evaluate(() => getInstalledScripts().map((item) => ({ name: item.name, version: item.version })));
+  expect(merged).toEqual([
+    { name: 'Existing Script', version: '2.0.0' },
+    { name: 'New Script', version: '1.0.0' },
+  ]);
+  const snapshot = await page.evaluate(() => JSON.parse(localStorage.getItem('sh_import_snapshot')));
+  expect(snapshot).toMatchObject({
+    schema: 'scripthunt-import-snapshot',
+    version: 1,
+    importType: 'installed',
+  });
+
+  await page.locator('.toast').last().getByRole('button', { name: 'Undo' }).click();
+  const restored = await page.evaluate(() => getInstalledScripts());
+  expect(restored).toHaveLength(1);
+  expect(restored[0]).toMatchObject({ name: 'Existing Script', version: '1.0.0' });
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.click('#btnExportInstalled');
+  const download = await downloadPromise;
+  const exported = JSON.parse(await fs.readFile(await download.path(), 'utf8'));
+  expect(exported.installed).toHaveLength(1);
+  expect(exported.installed[0]).toMatchObject({ name: 'Existing Script', version: '1.0.0' });
+});
+
 test('result icon buttons have accessible names', async ({ page }) => {
   await page.goto('/');
   await runSearch(page);