Feature/v2/toggle_for_auto_unzip (#4584)

## default 
<img width="1012" height="627"
alt="{BF57458D-50A6-4057-94F1-D6AB4628EFD8}"
src="https://github.com/user-attachments/assets/85e550ab-0aed-4341-be95-d5d3bc7146db"
/>

## disabled
<img width="1141" height="620"
alt="{140DB87B-05CF-4E0E-A14A-ED15075BD2EE}"
src="https://github.com/user-attachments/assets/e0f56e84-fb9d-4787-b5cb-ba7c5a54b1e1"
/>

## unzip options
<img width="530" height="255"
alt="{482CE185-73D5-4D90-91BB-B9305C711391}"
src="https://github.com/user-attachments/assets/609b18ee-4eae-4cee-afc1-5db01f9d1088"
/>
<img width="579" height="473"
alt="{4DFCA96D-792D-4370-8C62-4BA42C9F1A5F}"
src="https://github.com/user-attachments/assets/c67fa4af-04ef-41df-9420-65ce4247e25b"
/>

## pop up and maintains version metadata
<img width="1071" height="1220"
alt="{7F2A785C-5717-4A79-9D45-74BDA46DF273}"
src="https://github.com/user-attachments/assets/9374cd2a-b7e5-46c4-a722-e141ab42f0de"
/>

---------

Co-authored-by: Connor Yoh <connor@stirlingpdf.com>

frontend/src/hooks/tools/scannerImageSplit/useScannerImageSplitOperation.ts

@@ -1,8 +1,9 @@
+import { useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
-import { ToolType, useToolOperation } from '../shared/useToolOperation';
+import { ToolType, useToolOperation, ToolOperationConfig } from '../shared/useToolOperation';
 import { createStandardErrorHandler } from '../../../utils/toolErrorHandler';
 import { ScannerImageSplitParameters, defaultParameters } from './useScannerImageSplitParameters';
-import { zipFileService } from '../../../services/zipFileService';
+import { useToolResources } from '../shared/useToolResources';
 
 export const buildScannerImageSplitFormData = (parameters: ScannerImageSplitParameters, file: File): FormData => {
   const formData = new FormData();
@@ -15,40 +16,46 @@ export const buildScannerImageSplitFormData = (parameters: ScannerImageSplitPara
   return formData;
 };
 
-// Custom response handler to handle ZIP files that might be misidentified
-const scannerImageSplitResponseHandler = async (responseData: Blob, inputFiles: File[]): Promise<File[]> => {
-  try {
-    // Always try to extract as ZIP first, regardless of content-type
-    const extractionResult = await zipFileService.extractAllFiles(responseData);
-    if (extractionResult.success && extractionResult.extractedFiles.length > 0) {
-      return extractionResult.extractedFiles;
-    }
-  } catch (error) {
-    console.warn('Failed to extract as ZIP, treating as single file:', error);
-  }
-
-  // Fallback: treat as single file (PNG image)
-  const inputFileName = inputFiles[0]?.name || 'document';
-  const baseFileName = inputFileName.replace(/\.[^.]+$/, '');
-  const singleFile = new File([responseData], `${baseFileName}.png`, { type: 'image/png' });
-  return [singleFile];
-};
-
+// Static configuration object
 export const scannerImageSplitOperationConfig = {
   toolType: ToolType.singleFile,
   buildFormData: buildScannerImageSplitFormData,
   operationType: 'scannerImageSplit',
   endpoint: '/api/v1/misc/extract-image-scans',
-  multiFileEndpoint: false,
-  responseHandler: scannerImageSplitResponseHandler,
   defaultParameters,
 } as const;
 
 export const useScannerImageSplitOperation = () => {
   const { t } = useTranslation();
+  const { extractAllZipFiles } = useToolResources();
 
-  return useToolOperation<ScannerImageSplitParameters>({
+  // Custom response handler that extracts ZIP files containing images
+  // Can't add to exported config because it requires access to the hook so must be part of the hook
+  const responseHandler = useCallback(async (blob: Blob, originalFiles: File[]): Promise<File[]> => {
+    try {
+      // Scanner image split returns ZIP files with multiple images
+      const extractedFiles = await extractAllZipFiles(blob);
+
+      // If extraction succeeded and returned files, use them
+      if (extractedFiles.length > 0) {
+        return extractedFiles;
+      }
+    } catch (error) {
+      console.warn('Failed to extract as ZIP, treating as single file:', error);
+    }
+
+    // Fallback: treat as single file (PNG image)
+    const inputFileName = originalFiles[0]?.name || 'document';
+    const baseFileName = inputFileName.replace(/\.[^.]+$/, '');
+    const singleFile = new File([blob], `${baseFileName}.png`, { type: 'image/png' });
+    return [singleFile];
+  }, [extractAllZipFiles]);
+
+  const config: ToolOperationConfig<ScannerImageSplitParameters> = {
     ...scannerImageSplitOperationConfig,
+    responseHandler,
     getErrorMessage: createStandardErrorHandler(t('scannerImageSplit.error.failed', 'An error occurred while extracting image scans.'))
-  });
+  };
+
+  return useToolOperation(config);
 };

frontend/src/hooks/tools/shared/useToolOperation.ts

@@ -257,6 +257,7 @@ export const useToolOperation = <TParams>(
             processedFiles = [singleFile];
           } else {
             // Default: assume ZIP response for multi-file endpoints
+            // Note: extractZipFiles will check preferences.autoUnzip setting
             processedFiles = await extractZipFiles(response.data);
 
             if (processedFiles.length === 0) {

frontend/src/hooks/tools/shared/useToolResources.ts

@@ -1,9 +1,11 @@
 import { useState, useCallback, useEffect, useRef } from 'react';
 import { generateThumbnailForFile, generateThumbnailWithMetadata, ThumbnailWithMetadata } from '../../../utils/thumbnailUtils';
 import { zipFileService } from '../../../services/zipFileService';
+import { usePreferences } from '../../../contexts/PreferencesContext';
 
 
 export const useToolResources = () => {
+  const { preferences } = usePreferences();
   const [blobUrls, setBlobUrls] = useState<string[]>([]);
 
   const addBlobUrl = useCallback((url: string) => {
@@ -81,8 +83,20 @@ export const useToolResources = () => {
     return results;
   }, []);
 
-  const extractZipFiles = useCallback(async (zipBlob: Blob): Promise<File[]> => {
+  const extractZipFiles = useCallback(async (zipBlob: Blob, skipAutoUnzip = false): Promise<File[]> => {
     try {
+      // Check if we should extract based on preferences
+      const shouldExtract = await zipFileService.shouldUnzip(
+        zipBlob,
+        preferences.autoUnzip,
+        preferences.autoUnzipFileLimit,
+        skipAutoUnzip
+      );
+
+      if (!shouldExtract) {
+        return [new File([zipBlob], 'result.zip', { type: 'application/zip' })];
+      }
+
       const zipFile = new File([zipBlob], 'temp.zip', { type: 'application/zip' });
       const extractionResult = await zipFileService.extractPdfFiles(zipFile);
       return extractionResult.success ? extractionResult.extractedFiles : [];
@@ -90,32 +104,30 @@ export const useToolResources = () => {
       console.error('useToolResources.extractZipFiles - Error:', error);
       return [];
     }
-  }, []);
+  }, [preferences.autoUnzip, preferences.autoUnzipFileLimit]);
 
-  const extractAllZipFiles = useCallback(async (zipBlob: Blob): Promise<File[]> => {
+  const extractAllZipFiles = useCallback(async (zipBlob: Blob, skipAutoUnzip = false): Promise<File[]> => {
     try {
-      const JSZip = (await import('jszip')).default;
-      const zip = new JSZip();
+      // Check if we should extract based on preferences
+      const shouldExtract = await zipFileService.shouldUnzip(
+        zipBlob,
+        preferences.autoUnzip,
+        preferences.autoUnzipFileLimit,
+        skipAutoUnzip
+      );
 
-      const arrayBuffer = await zipBlob.arrayBuffer();
-      const zipContent = await zip.loadAsync(arrayBuffer);
-
-      const extractedFiles: File[] = [];
-
-      for (const [filename, file] of Object.entries(zipContent.files)) {
-        if (!file.dir) {
-          const content = await file.async('blob');
-          const extractedFile = new File([content], filename, { type: 'application/pdf' });
-          extractedFiles.push(extractedFile);
-        }
+      if (!shouldExtract) {
+        return [new File([zipBlob], 'result.zip', { type: 'application/zip' })];
       }
 
-      return extractedFiles;
+      const zipFile = new File([zipBlob], 'temp.zip', { type: 'application/zip' });
+      const extractionResult = await zipFileService.extractAllFiles(zipFile);
+      return extractionResult.success ? extractionResult.extractedFiles : [];
     } catch (error) {
-      console.error('Error in extractAllZipFiles:', error);
+      console.error('useToolResources.extractAllZipFiles - Error:', error);
       return [];
     }
-  }, []);
+  }, [preferences.autoUnzip, preferences.autoUnzipFileLimit]);
 
   const createDownloadInfo = useCallback(async (
     files: File[],