Feature/v2/file handling improvements (#4222)

# Description of Changes

A new universal file context rather than the splintered ones for the
main views, tools and manager we had before (manager still has its own
but its better integreated with the core context)
File context has been split it into a handful of different files
managing various file related issues separately to reduce the monolith -
FileReducer.ts - State management
  fileActions.ts - File operations
  fileSelectors.ts - Data access patterns
  lifecycle.ts - Resource cleanup and memory management
  fileHooks.ts - React hooks interface
  contexts.ts - Context providers
Improved thumbnail generation
Improved indexxedb handling
Stopped handling files as blobs were not necessary to improve
performance
A new library handling drag and drop
https://github.com/atlassian/pragmatic-drag-and-drop (Out of scope yes
but I broke the old one with the new filecontext and it needed doing so
it was a might as well)
A new library handling virtualisation on page editor
@tanstack/react-virtual, as above.
Quickly ripped out the last remnants of the old URL params stuff and
replaced with the beginnings of what will later become the new URL
navigation system (for now it just restores the tool name in url
behavior)
Fixed selected file not regestered when opening a tool
Fixed png thumbnails
Closes #(issue_number)

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

---------

Co-authored-by: Reece Browne <you@example.com>

frontend/src/utils/downloadUtils.ts

@@ -1,4 +1,4 @@
-import { FileWithUrl } from '../types/file';
+import { FileMetadata } from '../types/file';
 import { fileStorage } from '../services/fileStorage';
 import { zipFileService } from '../services/zipFileService';
 
@@ -26,8 +26,8 @@ export function downloadBlob(blob: Blob, filename: string): void {
  * @param file - The file object with storage information
  * @throws Error if file cannot be retrieved from storage
  */
-export async function downloadFileFromStorage(file: FileWithUrl): Promise<void> {
-  const lookupKey = file.id || file.name;
+export async function downloadFileFromStorage(file: FileMetadata): Promise<void> {
+  const lookupKey = file.id;
   const storedFile = await fileStorage.getFile(lookupKey);
   
   if (!storedFile) {
@@ -42,7 +42,7 @@ export async function downloadFileFromStorage(file: FileWithUrl): Promise<void>
  * Downloads multiple files as individual downloads
  * @param files - Array of files to download
  */
-export async function downloadMultipleFiles(files: FileWithUrl[]): Promise<void> {
+export async function downloadMultipleFiles(files: FileMetadata[]): Promise<void> {
   for (const file of files) {
     await downloadFileFromStorage(file);
   }
@@ -53,7 +53,7 @@ export async function downloadMultipleFiles(files: FileWithUrl[]): Promise<void>
  * @param files - Array of files to include in ZIP
  * @param zipFilename - Optional custom ZIP filename (defaults to timestamped name)
  */
-export async function downloadFilesAsZip(files: FileWithUrl[], zipFilename?: string): Promise<void> {
+export async function downloadFilesAsZip(files: FileMetadata[], zipFilename?: string): Promise<void> {
   if (files.length === 0) {
     throw new Error('No files provided for ZIP download');
   }
@@ -61,7 +61,7 @@ export async function downloadFilesAsZip(files: FileWithUrl[], zipFilename?: str
   // Convert stored files to File objects
   const fileObjects: File[] = [];
   for (const fileWithUrl of files) {
-    const lookupKey = fileWithUrl.id || fileWithUrl.name;
+    const lookupKey = fileWithUrl.id;
     const storedFile = await fileStorage.getFile(lookupKey);
     
     if (storedFile) {
@@ -94,7 +94,7 @@ export async function downloadFilesAsZip(files: FileWithUrl[], zipFilename?: str
  * @param options - Download options
  */
 export async function downloadFiles(
-  files: FileWithUrl[], 
+  files: FileMetadata[], 
   options: {
     forceZip?: boolean;
     zipFilename?: string;

frontend/src/utils/fileUtils.ts

@@ -1,9 +1,4 @@
-import { FileWithUrl } from "../types/file";
-import { StoredFile, fileStorage } from "../services/fileStorage";
-
-export function getFileId(file: File): string | null {
-  return (file as File & { id?: string }).id || null;
-}
+// Pure utility functions for file operations
 
 /**
  * Consolidated file size formatting utility
@@ -19,7 +14,7 @@ export function formatFileSize(bytes: number): string {
 /**
  * Get file date as string
  */
-export function getFileDate(file: File): string {
+export function getFileDate(file: File | { lastModified: number }): string {
   if (file.lastModified) {
     return new Date(file.lastModified).toLocaleString();
   }
@@ -29,107 +24,12 @@ export function getFileDate(file: File): string {
 /**
  * Get file size as string (legacy method for backward compatibility)
  */
-export function getFileSize(file: File): string {
+export function getFileSize(file: File | { size: number }): string {
   if (!file.size) return "Unknown";
   return formatFileSize(file.size);
 }
 
-/**
- * Create enhanced file object from stored file metadata
- * This eliminates the repeated pattern in FileManager
- */
-export function createEnhancedFileFromStored(storedFile: StoredFile, thumbnail?: string): FileWithUrl {
-  const enhancedFile: FileWithUrl = {
-    id: storedFile.id,
-    storedInIndexedDB: true,
-    url: undefined, // Don't create blob URL immediately to save memory
-    thumbnail: thumbnail || storedFile.thumbnail,
-    // File metadata
-    name: storedFile.name,
-    size: storedFile.size,
-    type: storedFile.type,
-    lastModified: storedFile.lastModified,
-    webkitRelativePath: '',
-    // Lazy-loading File interface methods
-    arrayBuffer: async () => {
-      const data = await fileStorage.getFileData(storedFile.id);
-      if (!data) throw new Error(`File ${storedFile.name} not found in IndexedDB - may have been purged`);
-      return data;
-    },
-    bytes: async () => {
-      return new Uint8Array();
-    },
-    slice: (start?: number, end?: number, contentType?: string) => {
-      // Return a promise-based slice that loads from IndexedDB
-      return new Blob([], { type: contentType || storedFile.type });
-    },
-    stream: () => {
-      throw new Error('Stream not implemented for IndexedDB files');
-    },
-    text: async () => {
-      const data = await fileStorage.getFileData(storedFile.id);
-      if (!data) throw new Error(`File ${storedFile.name} not found in IndexedDB - may have been purged`);
-      return new TextDecoder().decode(data);
-    },
-  } as FileWithUrl;
 
-  return enhancedFile;
-}
-
-/**
- * Load files from IndexedDB and convert to enhanced file objects
- */
-export async function loadFilesFromIndexedDB(): Promise<FileWithUrl[]> {
-  try {
-    await fileStorage.init();
-    const storedFiles = await fileStorage.getAllFileMetadata();
-
-    if (storedFiles.length === 0) {
-      return [];
-    }
-
-    const restoredFiles: FileWithUrl[] = storedFiles
-      .filter(storedFile => {
-        // Filter out corrupted entries
-        return storedFile &&
-               storedFile.name &&
-               typeof storedFile.size === 'number';
-      })
-      .map(storedFile => {
-        try {
-          return createEnhancedFileFromStored(storedFile as any);
-        } catch (error) {
-          console.error('Failed to restore file:', storedFile?.name || 'unknown', error);
-          return null;
-        }
-      })
-      .filter((file): file is FileWithUrl => file !== null);
-
-    return restoredFiles;
-  } catch (error) {
-    console.error('Failed to load files from IndexedDB:', error);
-    return [];
-  }
-}
-
-/**
- * Clean up blob URLs from file objects
- */
-export function cleanupFileUrls(files: FileWithUrl[]): void {
-  files.forEach(file => {
-    if (file.url && !file.url.startsWith('indexeddb:')) {
-      URL.revokeObjectURL(file.url);
-    }
-  });
-}
-
-/**
- * Check if file should use blob URL or IndexedDB direct access
- */
-export function shouldUseDirectIndexedDBAccess(file: FileWithUrl): boolean {
-  const FILE_SIZE_LIMIT = 100 * 1024 * 1024; // 100MB
-  return file.size > FILE_SIZE_LIMIT;
-}
 
 /**
  * Detects and normalizes file extension from filename
@@ -151,29 +51,3 @@ export function detectFileExtension(filename: string): string {
 
   return extension;
 }
-
-/**
- * Gets the filename without extension
- * @param filename - The filename to process
- * @returns Filename without extension
- */
-export function getFilenameWithoutExtension(filename: string): string {
-  if (!filename || typeof filename !== 'string') return '';
-
-  const parts = filename.split('.');
-  if (parts.length <= 1) return filename;
-
-  // Return all parts except the last one (extension)
-  return parts.slice(0, -1).join('.');
-}
-
-/**
- * Creates a new filename with a different extension
- * @param filename - Original filename
- * @param newExtension - New extension (without dot)
- * @returns New filename with the specified extension
- */
-export function changeFileExtension(filename: string, newExtension: string): string {
-  const nameWithoutExt = getFilenameWithoutExtension(filename);
-  return `${nameWithoutExt}.${newExtension}`;
-}

frontend/src/utils/storageUtils.ts

@@ -1,5 +1,4 @@
 import { StorageStats } from "../services/fileStorage";
-import { FileWithUrl } from "../types/file";
 
 /**
  * Storage operation types for incremental updates
@@ -12,7 +11,7 @@ export type StorageOperation = 'add' | 'remove' | 'clear';
 export function updateStorageStatsIncremental(
   currentStats: StorageStats,
   operation: StorageOperation,
-  files: FileWithUrl[] = []
+  files: File[] = []
 ): StorageStats {
   const filesSizeTotal = files.reduce((total, file) => total + file.size, 0);
   

frontend/src/utils/thumbnailUtils.ts

@@ -1,4 +1,9 @@
-import { getDocument } from "pdfjs-dist";
+import { pdfWorkerManager } from '../services/pdfWorkerManager';
+
+export interface ThumbnailWithMetadata {
+  thumbnail: string; // Always returns a thumbnail (placeholder if needed)
+  pageCount: number;
+}
 
 interface ColorScheme {
   bgTop: string;
@@ -11,19 +16,18 @@ interface ColorScheme {
 }
 
 /**
- * Calculate thumbnail scale based on file size
- * Smaller files get higher quality, larger files get lower quality
+ * Calculate thumbnail scale based on file size (modern 2024 scaling)
  */
 export function calculateScaleFromFileSize(fileSize: number): number {
   const MB = 1024 * 1024;
-
-  if (fileSize < 1 * MB) return 0.6;      // < 1MB: High quality
-  if (fileSize < 5 * MB) return 0.4;      // 1-5MB: Medium-high quality
-  if (fileSize < 15 * MB) return 0.3;     // 5-15MB: Medium quality
-  if (fileSize < 30 * MB) return 0.2;     // 15-30MB: Low-medium quality
-  return 0.15;                            // 30MB+: Low quality
+  if (fileSize < 10 * MB) return 1.0;   // Full quality for small files
+  if (fileSize < 50 * MB) return 0.8;   // High quality for common file sizes
+  if (fileSize < 200 * MB) return 0.6;  // Good quality for typical large files
+  if (fileSize < 500 * MB) return 0.4;  // Readable quality for large but manageable files
+  return 0.3;  // Still usable quality, not tiny
 }
 
+
 /**
  * Generate encrypted PDF thumbnail with lock icon
  */
@@ -125,16 +129,40 @@ function getFileTypeColorScheme(extension: string): ColorScheme {
     'PDF': { bgTop: '#FF6B6B20', bgBottom: '#FF6B6B10', border: '#FF6B6B40', icon: '#FF6B6B', badge: '#FF6B6B', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'DOC': { bgTop: '#4ECDC420', bgBottom: '#4ECDC410', border: '#4ECDC440', icon: '#4ECDC4', badge: '#4ECDC4', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'DOCX': { bgTop: '#4ECDC420', bgBottom: '#4ECDC410', border: '#4ECDC440', icon: '#4ECDC4', badge: '#4ECDC4', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'ODT': { bgTop: '#4ECDC420', bgBottom: '#4ECDC410', border: '#4ECDC440', icon: '#4ECDC4', badge: '#4ECDC4', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'TXT': { bgTop: '#95A5A620', bgBottom: '#95A5A610', border: '#95A5A640', icon: '#95A5A6', badge: '#95A5A6', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'RTF': { bgTop: '#95A5A620', bgBottom: '#95A5A610', border: '#95A5A640', icon: '#95A5A6', badge: '#95A5A6', textPrimary: '#FFFFFF', textSecondary: '#666666' },
 
     // Spreadsheets
     'XLS': { bgTop: '#2ECC7120', bgBottom: '#2ECC7110', border: '#2ECC7140', icon: '#2ECC71', badge: '#2ECC71', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'XLSX': { bgTop: '#2ECC7120', bgBottom: '#2ECC7110', border: '#2ECC7140', icon: '#2ECC71', badge: '#2ECC71', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'ODS': { bgTop: '#2ECC7120', bgBottom: '#2ECC7110', border: '#2ECC7140', icon: '#2ECC71', badge: '#2ECC71', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'CSV': { bgTop: '#2ECC7120', bgBottom: '#2ECC7110', border: '#2ECC7140', icon: '#2ECC71', badge: '#2ECC71', textPrimary: '#FFFFFF', textSecondary: '#666666' },
 
     // Presentations
     'PPT': { bgTop: '#E67E2220', bgBottom: '#E67E2210', border: '#E67E2240', icon: '#E67E22', badge: '#E67E22', textPrimary: '#FFFFFF', textSecondary: '#666666' },
     'PPTX': { bgTop: '#E67E2220', bgBottom: '#E67E2210', border: '#E67E2240', icon: '#E67E22', badge: '#E67E22', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'ODP': { bgTop: '#E67E2220', bgBottom: '#E67E2210', border: '#E67E2240', icon: '#E67E22', badge: '#E67E22', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+
+    // Images
+    'JPG': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'JPEG': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'PNG': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'GIF': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'BMP': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'TIFF': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'WEBP': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'SVG': { bgTop: '#FF9F4320', bgBottom: '#FF9F4310', border: '#FF9F4340', icon: '#FF9F43', badge: '#FF9F43', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+
+    // Web
+    'HTML': { bgTop: '#FD79A820', bgBottom: '#FD79A810', border: '#FD79A840', icon: '#FD79A8', badge: '#FD79A8', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+    'XML': { bgTop: '#FD79A820', bgBottom: '#FD79A810', border: '#FD79A840', icon: '#FD79A8', badge: '#FD79A8', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+
+    // Text/Markup
+    'MD': { bgTop: '#6C5CE720', bgBottom: '#6C5CE710', border: '#6C5CE740', icon: '#6C5CE7', badge: '#6C5CE7', textPrimary: '#FFFFFF', textSecondary: '#666666' },
+
+    // Email
+    'EML': { bgTop: '#A29BFE20', bgBottom: '#A29BFE10', border: '#A29BFE40', icon: '#A29BFE', badge: '#A29BFE', textPrimary: '#FFFFFF', textSecondary: '#666666' },
 
     // Archives
     'ZIP': { bgTop: '#9B59B620', bgBottom: '#9B59B610', border: '#9B59B640', icon: '#9B59B6', badge: '#9B59B6', textPrimary: '#FFFFFF', textSecondary: '#666666' },
@@ -275,16 +303,15 @@ function formatFileSize(bytes: number): string {
 
 async function generatePDFThumbnail(arrayBuffer: ArrayBuffer, file: File, scale: number): Promise<string> {
   try {
-    const pdf = await getDocument({
-      data: arrayBuffer,
+    const pdf = await pdfWorkerManager.createDocument(arrayBuffer, {
       disableAutoFetch: true,
       disableStream: true
-    }).promise;
+    });
 
     const thumbnail = await generateStandardPDFThumbnail(pdf, scale);
 
-    // Immediately clean up memory after thumbnail generation
-    pdf.destroy();
+    // Immediately clean up memory after thumbnail generation using worker manager
+    pdfWorkerManager.destroyDocument(pdf);
     return thumbnail;
   } catch (error) {
     if (error instanceof Error) {
@@ -298,52 +325,105 @@ async function generatePDFThumbnail(arrayBuffer: ArrayBuffer, file: File, scale:
 }
 
 /**
- * Generate thumbnail for any file type
- * Returns base64 data URL or undefined if generation fails
+ * Generate thumbnail for any file type - always returns a thumbnail (placeholder if needed)
  */
-export async function generateThumbnailForFile(file: File): Promise<string | undefined> {
-  // Skip thumbnail generation for very large files to avoid memory issues
-  if (file.size >= 100 * 1024 * 1024) { // 100MB limit
-    console.log('Skipping thumbnail generation for large file:', file.name);
+export async function generateThumbnailForFile(file: File): Promise<string> {
+  // Skip very large files
+  if (file.size >= 100 * 1024 * 1024) {
     return generatePlaceholderThumbnail(file);
   }
 
-  // Handle image files - use original file directly
+  // Handle image files - convert to data URL for persistence
   if (file.type.startsWith('image/')) {
-    return URL.createObjectURL(file);
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(reader.result as string);
+      reader.onerror = () => reject(reader.error);
+      reader.readAsDataURL(file);
+    });
   }
 
   // Handle PDF files
-  if (!file.type.startsWith('application/pdf')) {
-    console.log('File is not a PDF or image, generating placeholder:', file.name);
-    return generatePlaceholderThumbnail(file);
-  }
-
-  // Calculate quality scale based on file size
-  console.log('Generating thumbnail for', file.name);
-  const scale = calculateScaleFromFileSize(file.size);
-  console.log(`Using scale ${scale} for ${file.name} (${(file.size / 1024 / 1024).toFixed(1)}MB)`);
-
-  // Only read first 2MB for thumbnail generation to save memory
-  const chunkSize = 2 * 1024 * 1024; // 2MB
-  const chunk = file.slice(0, Math.min(chunkSize, file.size));
-  const arrayBuffer = await chunk.arrayBuffer();
-
-  try {
-    return await generatePDFThumbnail(arrayBuffer, file, scale);
-  } catch (error) {
-    if (error instanceof Error) {
-      if (error.name === 'InvalidPDFException') {
-        console.warn(`PDF structure issue for ${file.name} - using fallback thumbnail`);
-        // Return a placeholder or try with full file instead of chunk
-        const fullArrayBuffer = await file.arrayBuffer();
-        return await generatePDFThumbnail(fullArrayBuffer, file, scale);
-      } else {
-        console.warn('Unknown error thrown. Failed to generate thumbnail for', file.name, error);
-        return undefined;
+  if (file.type.startsWith('application/pdf')) {
+    const scale = calculateScaleFromFileSize(file.size);
+    
+    // Only read first 2MB for thumbnail generation to save memory
+    const chunkSize = 2 * 1024 * 1024; // 2MB
+    const chunk = file.slice(0, Math.min(chunkSize, file.size));
+    const arrayBuffer = await chunk.arrayBuffer();
+    
+    try {
+      return await generatePDFThumbnail(arrayBuffer, file, scale);
+    } catch (error) {
+      if (error instanceof Error && error.name === 'InvalidPDFException') {
+        console.warn(`PDF structure issue for ${file.name} - trying with full file`);
+        try {
+          // Try with full file instead of chunk
+          const fullArrayBuffer = await file.arrayBuffer();
+          return await generatePDFThumbnail(fullArrayBuffer, file, scale);
+        } catch (fullFileError) {
+          console.warn(`Full file PDF processing also failed for ${file.name} - using placeholder`);
+          return generatePlaceholderThumbnail(file);
+        }
       }
-    } else {
-      throw error; // Re-throw non-Error exceptions
+      console.warn(`PDF processing failed for ${file.name} - using placeholder:`, error);
+      return generatePlaceholderThumbnail(file);
     }
   }
+
+  // All other files get placeholder
+  return generatePlaceholderThumbnail(file);
 }
+
+/**
+ * Generate thumbnail and extract page count for a PDF file - always returns a valid thumbnail
+ */
+export async function generateThumbnailWithMetadata(file: File): Promise<ThumbnailWithMetadata> {
+  // Non-PDF files have no page count
+  if (!file.type.startsWith('application/pdf')) {
+    const thumbnail = await generateThumbnailForFile(file);
+    return { thumbnail, pageCount: 0 };
+  }
+
+  // Skip very large files
+  if (file.size >= 100 * 1024 * 1024) {
+    const thumbnail = generatePlaceholderThumbnail(file);
+    return { thumbnail, pageCount: 1 };
+  }
+
+  const scale = calculateScaleFromFileSize(file.size);
+  
+  try {
+    const arrayBuffer = await file.arrayBuffer();
+    const pdf = await pdfWorkerManager.createDocument(arrayBuffer);
+    
+    const pageCount = pdf.numPages;
+    const page = await pdf.getPage(1);
+    const viewport = page.getViewport({ scale });
+    const canvas = document.createElement("canvas");
+    canvas.width = viewport.width;
+    canvas.height = viewport.height;
+    const context = canvas.getContext("2d");
+
+    if (!context) {
+      pdfWorkerManager.destroyDocument(pdf);
+      throw new Error('Could not get canvas context');
+    }
+
+    await page.render({ canvasContext: context, viewport }).promise;
+    const thumbnail = canvas.toDataURL();
+    
+    pdfWorkerManager.destroyDocument(pdf);
+    return { thumbnail, pageCount };
+
+  } catch (error) {
+    if (error instanceof Error && error.name === "PasswordException") {
+      // Handle encrypted PDFs
+      const thumbnail = generateEncryptedPDFThumbnail(file);
+      return { thumbnail, pageCount: 1 };
+    }
+    
+    const thumbnail = generatePlaceholderThumbnail(file);
+    return { thumbnail, pageCount: 1 };
+  }
+}

frontend/src/utils/urlRouting.ts

@@ -0,0 +1,180 @@
+/**
+ * URL routing utilities for tool navigation
+ * Provides clean URL routing for the V2 tool system
+ */
+
+import { ModeType } from '../contexts/NavigationContext';
+
+export interface ToolRoute {
+  mode: ModeType;
+  toolKey?: string;
+}
+
+/**
+ * Parse the current URL to extract tool routing information
+ */
+export function parseToolRoute(): ToolRoute {
+  const path = window.location.pathname;
+  const searchParams = new URLSearchParams(window.location.search);
+  
+  // Extract tool from URL path (e.g., /split-pdf -> split)
+  const toolMatch = path.match(/\/([a-zA-Z-]+)(?:-pdf)?$/);
+  if (toolMatch) {
+    const toolKey = toolMatch[1].toLowerCase();
+    
+    // Map URL paths to tool keys and modes (excluding internal UI modes)
+    const toolMappings: Record<string, { mode: ModeType; toolKey: string }> = {
+      'split': { mode: 'split', toolKey: 'split' },
+      'merge': { mode: 'merge', toolKey: 'merge' },
+      'compress': { mode: 'compress', toolKey: 'compress' },
+      'convert': { mode: 'convert', toolKey: 'convert' },
+      'add-password': { mode: 'addPassword', toolKey: 'addPassword' },
+      'change-permissions': { mode: 'changePermissions', toolKey: 'changePermissions' },
+      'sanitize': { mode: 'sanitize', toolKey: 'sanitize' },
+      'ocr': { mode: 'ocr', toolKey: 'ocr' }
+    };
+    
+    const mapping = toolMappings[toolKey];
+    if (mapping) {
+      return {
+        mode: mapping.mode,
+        toolKey: mapping.toolKey
+      };
+    }
+  }
+  
+  // Check for query parameter fallback (e.g., ?tool=split)
+  const toolParam = searchParams.get('tool');
+  if (toolParam && isValidMode(toolParam)) {
+    return {
+      mode: toolParam as ModeType,
+      toolKey: toolParam
+    };
+  }
+  
+  // Default to page editor for home page
+  return {
+    mode: 'pageEditor'
+  };
+}
+
+/**
+ * Update the URL to reflect the current tool selection
+ * Internal UI modes (viewer, fileEditor, pageEditor) don't get URLs
+ */
+export function updateToolRoute(mode: ModeType, toolKey?: string): void {
+  const currentPath = window.location.pathname;
+  const searchParams = new URLSearchParams(window.location.search);
+  
+  // Don't create URLs for internal UI modes
+  if (mode === 'viewer' || mode === 'fileEditor' || mode === 'pageEditor') {
+    // If we're switching to an internal mode, clear any existing tool URL
+    if (currentPath !== '/') {
+      clearToolRoute();
+    }
+    return;
+  }
+  
+  let newPath = '/';
+  
+  // Map modes to URL paths (only for actual tools)
+  if (toolKey) {
+    const pathMappings: Record<string, string> = {
+      'split': '/split-pdf',
+      'merge': '/merge-pdf', 
+      'compress': '/compress-pdf',
+      'convert': '/convert-pdf',
+      'addPassword': '/add-password-pdf',
+      'changePermissions': '/change-permissions-pdf',
+      'sanitize': '/sanitize-pdf',
+      'ocr': '/ocr-pdf'
+    };
+    
+    newPath = pathMappings[toolKey] || `/${toolKey}`;
+  }
+  
+  // Remove tool query parameter since we're using path-based routing
+  searchParams.delete('tool');
+  
+  // Construct final URL
+  const queryString = searchParams.toString();
+  const fullUrl = newPath + (queryString ? `?${queryString}` : '');
+  
+  // Update URL without triggering page reload
+  if (currentPath !== newPath || window.location.search !== (queryString ? `?${queryString}` : '')) {
+    window.history.replaceState(null, '', fullUrl);
+  }
+}
+
+/**
+ * Clear tool routing and return to home page
+ */
+export function clearToolRoute(): void {
+  const searchParams = new URLSearchParams(window.location.search);
+  searchParams.delete('tool');
+  
+  const queryString = searchParams.toString();
+  const url = '/' + (queryString ? `?${queryString}` : '');
+  
+  window.history.replaceState(null, '', url);
+}
+
+/**
+ * Get clean tool name for display purposes
+ */
+export function getToolDisplayName(toolKey: string): string {
+  const displayNames: Record<string, string> = {
+    'split': 'Split PDF',
+    'merge': 'Merge PDF',
+    'compress': 'Compress PDF', 
+    'convert': 'Convert PDF',
+    'addPassword': 'Add Password',
+    'changePermissions': 'Change Permissions',
+    'sanitize': 'Sanitize PDF',
+    'ocr': 'OCR PDF'
+  };
+  
+  return displayNames[toolKey] || toolKey;
+}
+
+/**
+ * Check if a mode is valid
+ */
+function isValidMode(mode: string): mode is ModeType {
+  const validModes: ModeType[] = [
+    'viewer', 'pageEditor', 'fileEditor', 'merge', 'split', 
+    'compress', 'ocr', 'convert', 'addPassword', 'changePermissions', 'sanitize'
+  ];
+  return validModes.includes(mode as ModeType);
+}
+
+/**
+ * Generate shareable URL for current tool state
+ * Only generates URLs for actual tools, not internal UI modes
+ */
+export function generateShareableUrl(mode: ModeType, toolKey?: string): string {
+  const baseUrl = window.location.origin;
+  
+  // Don't generate URLs for internal UI modes
+  if (mode === 'viewer' || mode === 'fileEditor' || mode === 'pageEditor') {
+    return baseUrl;
+  }
+  
+  if (toolKey) {
+    const pathMappings: Record<string, string> = {
+      'split': '/split-pdf',
+      'merge': '/merge-pdf',
+      'compress': '/compress-pdf', 
+      'convert': '/convert-pdf',
+      'addPassword': '/add-password-pdf',
+      'changePermissions': '/change-permissions-pdf',
+      'sanitize': '/sanitize-pdf',
+      'ocr': '/ocr-pdf'
+    };
+    
+    const path = pathMappings[toolKey] || `/${toolKey}`;
+    return `${baseUrl}${path}`;
+  }
+  
+  return baseUrl;
+}