Restore filewithid changes

frontend/src/components/fileEditor/FileEditorThumbnail.tsx

@@ -61,8 +61,8 @@ const FileEditorThumbnail = ({
 
   // Resolve the actual File object for pin/unpin operations
   const actualFile = useMemo(() => {
-    return activeFiles.find((f: File) => f.name === file.name && f.size === file.size);
+    return activeFiles.find(f => f.fileId === file.id);
-  }, [activeFiles, file.name, file.size]);
+  }, [activeFiles, file.id]);
   const isPinned = actualFile ? isFilePinned(actualFile) : false;
 
   const downloadSelectedFile = useCallback(() => {

frontend/src/components/pageEditor/FileThumbnail.tsx

@@ -61,8 +61,8 @@ const FileThumbnail = ({
 
   // Resolve the actual File object for pin/unpin operations
   const actualFile = useMemo(() => {
-    return activeFiles.find((f: File) => f.name === file.name && f.size === file.size);
+    return activeFiles.find(f => f.fileId === file.id);
-  }, [activeFiles, file.name, file.size]);
+  }, [activeFiles, file.id]);
   const isPinned = actualFile ? isFilePinned(actualFile) : false;
 
   const downloadSelectedFile = useCallback(() => {

frontend/src/contexts/FileContext.tsx

@@ -19,7 +19,10 @@ import {
   FileContextStateValue,
   FileContextActionsValue,
   FileContextActions,
-  FileRecord
+  FileId,
+  FileRecord,
+  FileWithId,
+  createFileWithId
 } from '../types/fileContext';
 
 // Import modular components
@@ -29,7 +32,6 @@ import { AddedFile, addFiles, consumeFiles, undoConsumeFiles, createFileActions
 import { FileLifecycleManager } from './file/lifecycle';
 import { FileStateContext, FileActionsContext } from './file/contexts';
 import { IndexedDBProvider, useIndexedDB } from './IndexedDBContext';
-import { FileId } from '../types/file';
 
 const DEBUG = process.env.NODE_ENV === 'development';
 
@@ -79,7 +81,7 @@ function FileContextInner({
   }
 
   // File operations using unified addFiles helper with persistence
-  const addRawFiles = useCallback(async (files: File[], options?: { insertAfterPageId?: string; selectFiles?: boolean }): Promise<File[]> => {
+  const addRawFiles = useCallback(async (files: File[], options?: { insertAfterPageId?: string; selectFiles?: boolean }): Promise<FileWithId[]> => {
     const addedFilesWithIds = await addFiles('raw', { files, ...options }, stateRef, filesRef, dispatch, lifecycleManager);
 
     // Auto-select the newly added files if requested
@@ -98,15 +100,15 @@ function FileContextInner({
       }));
     }
 
-    return addedFilesWithIds.map(({ file }) => file);
+    return addedFilesWithIds.map(({ file, id }) => createFileWithId(file, id));
   }, [indexedDB, enablePersistence]);
 
-  const addProcessedFiles = useCallback(async (filesWithThumbnails: Array<{ file: File; thumbnail?: string; pageCount?: number }>): Promise<File[]> => {
+  const addProcessedFiles = useCallback(async (filesWithThumbnails: Array<{ file: File; thumbnail?: string; pageCount?: number }>): Promise<FileWithId[]> => {
     const result = await addFiles('processed', { filesWithThumbnails }, stateRef, filesRef, dispatch, lifecycleManager);
-    return result.map(({ file }) => file);
+    return result.map(({ file, id }) => createFileWithId(file, id));
   }, []);
 
-  const addStoredFiles = useCallback(async (filesWithMetadata: Array<{ file: File; originalId: FileId; metadata: any }>, options?: { selectFiles?: boolean }): Promise<File[]> => {
+  const addStoredFiles = useCallback(async (filesWithMetadata: Array<{ file: File; originalId: FileId; metadata: any }>, options?: { selectFiles?: boolean }): Promise<FileWithId[]> => {
     const result = await addFiles('stored', { filesWithMetadata }, stateRef, filesRef, dispatch, lifecycleManager);
 
     // Auto-select the newly added files if requested
@@ -114,7 +116,7 @@ function FileContextInner({
       selectFiles(result);
     }
 
-    return result.map(({ file }) => file);
+    return result.map(({ file, id }) => createFileWithId(file, id));
   }, []);
 
   // Action creators
@@ -140,24 +142,14 @@ function FileContextInner({
     });
   }, []);
 
-  // File-to-ID wrapper functions for pinning
+  // File pinning functions - use FileWithId directly
-  const pinFileWrapper = useCallback((file: File) => {
+  const pinFileWrapper = useCallback((file: FileWithId) => {
-    const fileId = findFileId(file);
+    baseActions.pinFile(file.fileId);
-    if (fileId) {
+  }, [baseActions]);
-      baseActions.pinFile(fileId);
-    } else {
-      console.warn('File not found for pinning:', file.name);
-    }
-  }, [baseActions, findFileId]);
 
-  const unpinFileWrapper = useCallback((file: File) => {
+  const unpinFileWrapper = useCallback((file: FileWithId) => {
-    const fileId = findFileId(file);
+    baseActions.unpinFile(file.fileId);
-    if (fileId) {
+  }, [baseActions]);
-      baseActions.unpinFile(fileId);
-    } else {
-      console.warn('File not found for unpinning:', file.name);
-    }
-  }, [baseActions, findFileId]);
 
   // Complete actions object
   const actions = useMemo<FileContextActions>(() => ({

frontend/src/contexts/file/fileHooks.ts

@@ -9,7 +9,7 @@ import {
   FileContextStateValue,
   FileContextActionsValue
 } from './contexts';
-import { FileRecord } from '../../types/fileContext';
+import { FileRecord, FileWithId } from '../../types/fileContext';
 import { FileId } from '../../types/file';
 
 /**
@@ -123,7 +123,7 @@ export function useFileRecord(fileId: FileId): { file?: File; record?: FileRecor
 /**
  * Hook for all files (use sparingly - causes re-renders on file list changes)
  */
-export function useAllFiles(): { files: File[]; records: FileRecord[]; fileIds: FileId[] } {
+export function useAllFiles(): { files: FileWithId[]; records: FileRecord[]; fileIds: FileId[] } {
   const { state, selectors } = useFileState();
 
   return useMemo(() => ({
@@ -136,7 +136,7 @@ export function useAllFiles(): { files: File[]; records: FileRecord[]; fileIds:
 /**
  * Hook for selected files (optimized for selection-based UI)
  */
-export function useSelectedFiles(): { files: File[]; records: FileRecord[]; fileIds: FileId[] } {
+export function useSelectedFiles(): { files: FileWithId[]; records: FileRecord[]; fileIds: FileId[] } {
   const { state, selectors } = useFileState();
 
   return useMemo(() => ({

frontend/src/contexts/file/fileSelectors.ts

@@ -6,7 +6,9 @@ import { FileId } from '../../types/file';
 import {
   FileRecord,
   FileContextState,
-  FileContextSelectors
+  FileContextSelectors,
+  FileWithId,
+  createFileWithId
 } from '../../types/fileContext';
 
 /**
@@ -17,11 +19,19 @@ export function createFileSelectors(
   filesRef: React.MutableRefObject<Map<FileId, File>>
 ): FileContextSelectors {
   return {
-    getFile: (id: FileId) => filesRef.current.get(id),
+    getFile: (id: FileId) => {
+      const file = filesRef.current.get(id);
+      return file ? createFileWithId(file, id) : undefined;
+    },
 
     getFiles: (ids?: FileId[]) => {
       const currentIds = ids || stateRef.current.files.ids;
-      return currentIds.map(id => filesRef.current.get(id)).filter(Boolean) as File[];
+      return currentIds
+        .map(id => {
+          const file = filesRef.current.get(id);
+          return file ? createFileWithId(file, id) : undefined;
+        })
+        .filter(Boolean) as FileWithId[];
     },
 
     getFileRecord: (id: FileId) => stateRef.current.files.byId[id],
@@ -35,8 +45,11 @@ export function createFileSelectors(
 
     getSelectedFiles: () => {
       return stateRef.current.ui.selectedFileIds
-        .map(id => filesRef.current.get(id))
+        .map(id => {
-        .filter(Boolean) as File[];
+          const file = filesRef.current.get(id);
+          return file ? createFileWithId(file, id) : undefined;
+        })
+        .filter(Boolean) as FileWithId[];
     },
 
     getSelectedFileRecords: () => {
@@ -52,8 +65,11 @@ export function createFileSelectors(
 
     getPinnedFiles: () => {
       return Array.from(stateRef.current.pinnedFiles)
-        .map(id => filesRef.current.get(id))
+        .map(id => {
-        .filter(Boolean) as File[];
+          const file = filesRef.current.get(id);
+          return file ? createFileWithId(file, id) : undefined;
+        })
+        .filter(Boolean) as FileWithId[];
     },
 
     getPinnedFileRecords: () => {
@@ -62,16 +78,8 @@ export function createFileSelectors(
         .filter(Boolean);
     },
 
-    isFilePinned: (file: File) => {
+    isFilePinned: (file: FileWithId) => {
-      // Find FileId by matching File object properties
+      return stateRef.current.pinnedFiles.has(file.fileId);
-      const fileId = (Object.keys(stateRef.current.files.byId) as FileId[]).find(id => {
-        const storedFile = filesRef.current.get(id);
-        return storedFile &&
-               storedFile.name === file.name &&
-               storedFile.size === file.size &&
-               storedFile.lastModified === file.lastModified;
-      });
-      return fileId ? stateRef.current.pinnedFiles.has(fileId) : false;
     },
 
     // Stable signature for effects - prevents unnecessary re-renders

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

@@ -6,10 +6,8 @@ import { useToolState, type ProcessingProgress } from './useToolState';
 import { useToolApiCalls, type ApiCallsConfig } from './useToolApiCalls';
 import { useToolResources } from './useToolResources';
 import { extractErrorMessage } from '../../../utils/toolErrorHandler';
-import { createOperation } from '../../../utils/toolOperationTracker';
+import { FileWithId, extractFiles, FileId, FileRecord } from '../../../types/fileContext';
 import { ResponseHandler } from '../../../utils/toolResponseProcessor';
-import { FileId } from '../../../types/file';
-import { FileRecord } from '../../../types/fileContext';
 
 // Re-export for backwards compatibility
 export type { ProcessingProgress, ResponseHandler };
@@ -104,7 +102,7 @@ export interface ToolOperationHook<TParams = void> {
   progress: ProcessingProgress | null;
 
   // Actions
-  executeOperation: (params: TParams, selectedFiles: File[]) => Promise<void>;
+  executeOperation: (params: TParams, selectedFiles: FileWithId[]) => Promise<void>;
   resetResults: () => void;
   clearError: () => void;
   cancelOperation: () => void;
@@ -130,7 +128,7 @@ export const useToolOperation = <TParams>(
   config: ToolOperationConfig<TParams>
 ): ToolOperationHook<TParams> => {
   const { t } = useTranslation();
-  const { recordOperation, markOperationApplied, markOperationFailed, addFiles, consumeFiles, undoConsumeFiles, findFileId, actions: fileActions, selectors } = useFileContext();
+  const { addFiles, consumeFiles, undoConsumeFiles, actions: fileActions, selectors } = useFileContext();
 
   // Composed hooks
   const { state, actions } = useToolState();
@@ -146,7 +144,7 @@ export const useToolOperation = <TParams>(
 
   const executeOperation = useCallback(async (
     params: TParams,
-    selectedFiles: File[]
+    selectedFiles: FileWithId[]
   ): Promise<void> => {
     // Validation
     if (selectedFiles.length === 0) {
@@ -160,9 +158,6 @@ export const useToolOperation = <TParams>(
       return;
     }
 
-    // Setup operation tracking
-    const { operation, operationId, fileId } = createOperation(config.operationType, params, selectedFiles);
-    recordOperation(fileId, operation);
 
     // Reset state
     actions.setLoading(true);
@@ -173,6 +168,9 @@ export const useToolOperation = <TParams>(
     try {
       let processedFiles: File[];
 
+      // Convert FileWithId to regular File objects for API processing
+      const validRegularFiles = extractFiles(validFiles);
+
       switch (config.toolType) {
         case ToolType.singleFile:
           // Individual file processing - separate API call per file
@@ -184,7 +182,7 @@ export const useToolOperation = <TParams>(
           };
           processedFiles = await processFiles(
             params,
-            validFiles,
+            validRegularFiles,
             apiCallsConfig,
             actions.setProgress,
             actions.setStatus
@@ -194,7 +192,7 @@ export const useToolOperation = <TParams>(
         case ToolType.multiFile:
           // Multi-file processing - single API call with all files
           actions.setStatus('Processing files...');
-          const formData = config.buildFormData(params, validFiles);
+          const formData = config.buildFormData(params, validRegularFiles);
           const endpoint = typeof config.endpoint === 'function' ? config.endpoint(params) : config.endpoint;
 
           const response = await axios.post(endpoint, formData, { responseType: 'blob' });
@@ -202,11 +200,11 @@ export const useToolOperation = <TParams>(
           // Multi-file responses are typically ZIP files that need extraction, but some may return single PDFs
           if (config.responseHandler) {
             // Use custom responseHandler for multi-file (handles ZIP extraction)
-            processedFiles = await config.responseHandler(response.data, validFiles);
+            processedFiles = await config.responseHandler(response.data, validRegularFiles);
           } else if (response.data.type === 'application/pdf' ||
                      (response.headers && response.headers['content-type'] === 'application/pdf')) {
             // Single PDF response (e.g. split with merge option) - use original filename
-            const originalFileName = validFiles[0]?.name || 'document.pdf';
+            const originalFileName = validRegularFiles[0]?.name || 'document.pdf';
             const singleFile = new File([response.data], originalFileName, { type: 'application/pdf' });
             processedFiles = [singleFile];
           } else {
@@ -222,7 +220,7 @@ export const useToolOperation = <TParams>(
 
         case ToolType.custom:
           actions.setStatus('Processing files...');
-          processedFiles = await config.customProcessor(params, validFiles);
+          processedFiles = await config.customProcessor(params, validRegularFiles);
           break;
       }
 
@@ -246,17 +244,13 @@ export const useToolOperation = <TParams>(
         
         // Build parallel arrays of IDs and records for undo tracking
         for (const file of validFiles) {
-          const fileId = findFileId(file);
+          const fileId = file.fileId;
-          if (fileId) {
+          const record = selectors.getFileRecord(fileId);
-            const record = selectors.getFileRecord(fileId);
+          if (record) {
-            if (record) {
+            inputFileIds.push(fileId);
-              inputFileIds.push(fileId);
+            inputFileRecords.push(record);
-              inputFileRecords.push(record);
-            } else {
-              console.warn(`No file record found for file: ${file.name}`);
-            }
           } else {
-            console.warn(`No file ID found for file: ${file.name}`);
+            console.warn(`No file record found for file: ${file.name}`);
           }
         }
         
@@ -264,24 +258,22 @@ export const useToolOperation = <TParams>(
         
         // Store operation data for undo (only store what we need to avoid memory bloat)
         lastOperationRef.current = {
-          inputFiles: validFiles, // Keep original File objects for undo
+          inputFiles: extractFiles(validFiles), // Convert to File objects for undo
           inputFileRecords: inputFileRecords.map(record => ({ ...record })), // Deep copy to avoid reference issues
           outputFileIds
         };
 
-        markOperationApplied(fileId, operationId);
       }
 
     } catch (error: any) {
       const errorMessage = config.getErrorMessage?.(error) || extractErrorMessage(error);
       actions.setError(errorMessage);
       actions.setStatus('');
-      markOperationFailed(fileId, operationId, errorMessage);
     } finally {
       actions.setLoading(false);
       actions.setProgress(null);
     }
-  }, [t, config, actions, recordOperation, markOperationApplied, markOperationFailed, addFiles, consumeFiles, findFileId, processFiles, generateThumbnails, createDownloadInfo, cleanupBlobUrls, extractZipFiles, extractAllZipFiles]);
+  }, [t, config, actions, addFiles, consumeFiles, processFiles, generateThumbnails, createDownloadInfo, cleanupBlobUrls, extractZipFiles, extractAllZipFiles]);
 
   const cancelOperation = useCallback(() => {
     cancelApiCalls();

frontend/src/hooks/usePDFProcessor.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback } from 'react';
 import { PDFDocument, PDFPage } from '../types/pageEditor';
 import { pdfWorkerManager } from '../services/pdfWorkerManager';
+import { createQuickKey } from '../types/fileContext';
 
 export function usePDFProcessor() {
   const [loading, setLoading] = useState(false);
@@ -75,7 +76,7 @@ export function usePDFProcessor() {
       // Create pages without thumbnails initially - load them lazily
       for (let i = 1; i <= totalPages; i++) {
         pages.push({
-          id: `${file.name}-page-${i}`,
+          id: `${createQuickKey(file)}-page-${i}`,
           pageNumber: i,
           originalPageNumber: i,
           thumbnail: null, // Will be loaded lazily

frontend/src/hooks/useThumbnailGeneration.ts

@@ -1,5 +1,6 @@
 import { useCallback, useRef } from 'react';
 import { thumbnailGenerationService } from '../services/thumbnailGenerationService';
+import { createQuickKey } from '../types/fileContext';
 import { FileId } from '../types/file';
 
 // Request queue to handle concurrent thumbnail requests
@@ -71,8 +72,8 @@ async function processRequestQueue() {
 
           console.log(`📸 Batch generating ${requests.length} thumbnails for pages: ${pageNumbers.slice(0, 5).join(', ')}${pageNumbers.length > 5 ? '...' : ''}`);
 
-          // Use file name as fileId for PDF document caching
+          // Use quickKey for PDF document caching (same metadata, consistent format)
-          const fileId = file.name + '_' + file.size + '_' + file.lastModified as FileId;
+          const fileId = createQuickKey(file) as FileId;
 
           const results = await thumbnailGenerationService.generateThumbnails(
             fileId,

frontend/src/services/enhancedPDFProcessingService.ts

@@ -5,6 +5,7 @@ import { FileHasher } from '../utils/fileHash';
 import { FileAnalyzer } from './fileAnalyzer';
 import { ProcessingErrorHandler } from './processingErrorHandler';
 import { pdfWorkerManager } from './pdfWorkerManager';
+import { createQuickKey } from '../types/fileContext';
 
 export class EnhancedPDFProcessingService {
   private static instance: EnhancedPDFProcessingService;
@@ -201,7 +202,7 @@ export class EnhancedPDFProcessingService {
         const thumbnail = await this.renderPageThumbnail(page, config.thumbnailQuality);
 
         pages.push({
-          id: `${file.name}-page-${i}`,
+          id: `${createQuickKey(file)}-page-${i}`,
           pageNumber: i,
           thumbnail,
           rotation: 0,
@@ -251,7 +252,7 @@ export class EnhancedPDFProcessingService {
       const thumbnail = await this.renderPageThumbnail(page, config.thumbnailQuality);
 
       pages.push({
-        id: `${file.name}-page-${i}`,
+        id: `${createQuickKey(file)}-page-${i}`,
         pageNumber: i,
         thumbnail,
         rotation: 0,
@@ -266,7 +267,7 @@ export class EnhancedPDFProcessingService {
     // Create placeholder pages for remaining pages
     for (let i = priorityCount + 1; i <= totalPages; i++) {
       pages.push({
-        id: `${file.name}-page-${i}`,
+        id: `${createQuickKey(file)}-page-${i}`,
         pageNumber: i,
         thumbnail: null, // Will be loaded lazily
         rotation: 0,
@@ -313,7 +314,7 @@ export class EnhancedPDFProcessingService {
       const thumbnail = await this.renderPageThumbnail(page, config.thumbnailQuality);
 
       pages.push({
-        id: `${file.name}-page-${i}`,
+        id: `${createQuickKey(file)}-page-${i}`,
         pageNumber: i,
         thumbnail,
         rotation: 0,
@@ -334,7 +335,7 @@ export class EnhancedPDFProcessingService {
     // Create placeholders for remaining pages
     for (let i = firstChunkEnd + 1; i <= totalPages; i++) {
       pages.push({
-        id: `${file.name}-page-${i}`,
+        id: `${createQuickKey(file)}-page-${i}`,
         pageNumber: i,
         thumbnail: null,
         rotation: 0,
@@ -368,7 +369,7 @@ export class EnhancedPDFProcessingService {
     const pages: PDFPage[] = [];
     for (let i = 1; i <= totalPages; i++) {
       pages.push({
-        id: `${file.name}-page-${i}`,
+        id: `${createQuickKey(file)}-page-${i}`,
         pageNumber: i,
         thumbnail: null,
         rotation: 0,

frontend/src/services/pdfProcessingService.ts

@@ -1,6 +1,7 @@
 import { ProcessedFile, ProcessingState, PDFPage } from '../types/processing';
 import { ProcessingCache } from './processingCache';
 import { pdfWorkerManager } from './pdfWorkerManager';
+import { createQuickKey } from '../types/fileContext';
 
 export class PDFProcessingService {
   private static instance: PDFProcessingService;
@@ -113,7 +114,7 @@ export class PDFProcessingService {
         const thumbnail = canvas.toDataURL();
 
         pages.push({
-          id: `${file.name}-page-${i}`,
+          id: `${createQuickKey(file)}-page-${i}`,
           pageNumber: i,
           thumbnail,
           rotation: 0,

frontend/src/tests/convert/ConvertIntegration.test.tsx

@@ -18,6 +18,8 @@ import { FileContextProvider } from '../../contexts/FileContext';
 import { I18nextProvider } from 'react-i18next';
 import i18n from '../../i18n/config';
 import axios from 'axios';
+import { createTestFileWithId } from '../utils/testFileHelpers';
+import { FileWithId } from '../../types/fileContext';
 
 // Mock axios
 vi.mock('axios');
@@ -55,9 +57,9 @@ const createTestFile = (name: string, content: string, type: string): File => {
   return new File([content], name, { type });
 };
 
-const createPDFFile = (): File => {
+const createPDFFile = (): FileWithId => {
   const pdfContent = '%PDF-1.4\n1 0 obj\n<<\n/Type /Catalog\n/Pages 2 0 R\n>>\nendobj\ntrailer\n<<\n/Size 2\n/Root 1 0 R\n>>\nstartxref\n0\n%%EOF';
-  return createTestFile('test.pdf', pdfContent, 'application/pdf');
+  return createTestFileWithId('test.pdf', pdfContent, 'application/pdf');
 };
 
 // Test wrapper component
@@ -162,7 +164,7 @@ describe('Convert Tool Integration Tests', () => {
         wrapper: TestWrapper
       });
 
-      const testFile = createTestFile('invalid.txt', 'not a pdf', 'text/plain');
+      const testFile = createTestFileWithId('invalid.txt', 'not a pdf', 'text/plain');
       const parameters: ConvertParameters = {
         fromExtension: 'pdf',
         toExtension: 'png',
@@ -426,7 +428,7 @@ describe('Convert Tool Integration Tests', () => {
       });
       const files = [
         createPDFFile(),
-        createTestFile('test2.pdf', '%PDF-1.4...', 'application/pdf')
+        createTestFileWithId('test2.pdf', '%PDF-1.4...', 'application/pdf')
       ]
       const parameters: ConvertParameters = {
         fromExtension: 'pdf',
@@ -527,7 +529,7 @@ describe('Convert Tool Integration Tests', () => {
         wrapper: TestWrapper
       });
 
-      const corruptedFile = createTestFile('corrupted.pdf', 'not-a-pdf', 'application/pdf');
+      const corruptedFile = createTestFileWithId('corrupted.pdf', 'not-a-pdf', 'application/pdf');
       const parameters: ConvertParameters = {
         fromExtension: 'pdf',
         toExtension: 'png',

frontend/src/tests/utils/testFileHelpers.ts

@@ -0,0 +1,28 @@
+/**
+ * Test utilities for creating FileWithId objects in tests
+ */
+
+import { FileWithId, createFileWithId } from '../../types/fileContext';
+
+/**
+ * Create a FileWithId object for testing purposes
+ */
+export function createTestFileWithId(
+  name: string,
+  content: string = 'test content',
+  type: string = 'application/pdf'
+): FileWithId {
+  const file = new File([content], name, { type });
+  return createFileWithId(file);
+}
+
+/**
+ * Create multiple FileWithId objects for testing
+ */
+export function createTestFilesWithId(
+  files: Array<{ name: string; content?: string; type?: string }>
+): FileWithId[] {
+  return files.map(({ name, content = 'test content', type = 'application/pdf' }) =>
+    createTestFileWithId(name, content, type)
+  );
+}

frontend/src/types/fileContext.ts

@@ -5,6 +5,9 @@
 import { PageOperation } from './pageEditor';
 import { FileId, FileMetadata } from './file';
 
+// Re-export FileId for convenience
+export type { FileId };
+
 export type ModeType =
   | 'viewer'
   | 'pageEditor'
@@ -82,6 +85,67 @@ export function createQuickKey(file: File): string {
   return `${file.name}|${file.size}|${file.lastModified}`;
 }
 
+// File with embedded UUID - replaces loose File + FileId parameter passing
+export interface FileWithId extends File {
+  readonly fileId: FileId;
+  readonly quickKey: string; // Fast deduplication key: name|size|lastModified
+}
+
+// Type guard to check if a File object has an embedded fileId
+export function isFileWithId(file: File): file is FileWithId {
+  return 'fileId' in file && typeof (file as any).fileId === 'string' &&
+         'quickKey' in file && typeof (file as any).quickKey === 'string';
+}
+
+// Create a FileWithId from a regular File object
+export function createFileWithId(file: File, id?: FileId): FileWithId {
+  const fileId = id || createFileId();
+  const quickKey = createQuickKey(file);
+  
+  // File properties are not enumerable, so we need to copy them explicitly
+  // This avoids prototype chain issues while preserving all File functionality
+  const fileWithId = {
+    // Explicitly copy File properties (they're not enumerable)
+    name: file.name,
+    size: file.size,
+    type: file.type,
+    lastModified: file.lastModified,
+    webkitRelativePath: file.webkitRelativePath,
+    
+    // Add our custom properties
+    fileId: fileId,
+    quickKey: quickKey,
+    
+    // Preserve File prototype methods by binding them to the original file
+    arrayBuffer: file.arrayBuffer.bind(file),
+    slice: file.slice.bind(file),
+    stream: file.stream.bind(file),
+    text: file.text.bind(file)
+  } as FileWithId;
+  
+  return fileWithId;
+}
+
+// Extract FileIds from FileWithId array
+export function extractFileIds(files: FileWithId[]): FileId[] {
+  return files.map(file => file.fileId);
+}
+
+// Extract regular File objects from FileWithId array
+export function extractFiles(files: FileWithId[]): File[] {
+  return files as File[];
+}
+
+// Check if an object is a File or FileWithId (replaces instanceof File checks)
+export function isFileObject(obj: any): obj is File | FileWithId {
+  return obj && 
+         typeof obj.name === 'string' &&
+         typeof obj.size === 'number' &&
+         typeof obj.type === 'string' &&
+         typeof obj.lastModified === 'number' &&
+         typeof obj.arrayBuffer === 'function';
+}
+
 
 
 export function toFileRecord(file: File, id?: FileId): FileRecord {
@@ -215,18 +279,18 @@ export type FileContextAction =
 
 export interface FileContextActions {
   // File management - lightweight actions only
-  addFiles: (files: File[], options?: { insertAfterPageId?: string; selectFiles?: boolean }) => Promise<File[]>;
+  addFiles: (files: File[], options?: { insertAfterPageId?: string; selectFiles?: boolean }) => Promise<FileWithId[]>;
-  addProcessedFiles: (filesWithThumbnails: Array<{ file: File; thumbnail?: string; pageCount?: number }>) => Promise<File[]>;
+  addProcessedFiles: (filesWithThumbnails: Array<{ file: File; thumbnail?: string; pageCount?: number }>) => Promise<FileWithId[]>;
-  addStoredFiles: (filesWithMetadata: Array<{ file: File; originalId: FileId; metadata: FileMetadata }>, options?: { selectFiles?: boolean }) => Promise<File[]>;
+  addStoredFiles: (filesWithMetadata: Array<{ file: File; originalId: FileId; metadata: FileMetadata }>, options?: { selectFiles?: boolean }) => Promise<FileWithId[]>;
   removeFiles: (fileIds: FileId[], deleteFromStorage?: boolean) => Promise<void>;
   updateFileRecord: (id: FileId, updates: Partial<FileRecord>) => void;
   reorderFiles: (orderedFileIds: FileId[]) => void;
   clearAllFiles: () => Promise<void>;
   clearAllData: () => Promise<void>;
 
-  // File pinning
+  // File pinning - accepts FileWithId for safer type checking
-  pinFile: (file: File) => void;
+  pinFile: (file: FileWithId) => void;
-  unpinFile: (file: File) => void;
+  unpinFile: (file: FileWithId) => void;
 
   // File consumption (replace unpinned files with outputs)
   consumeFiles: (inputFileIds: FileId[], outputFiles: File[]) => Promise<FileId[]>;
@@ -253,26 +317,17 @@ export interface FileContextActions {
 
 // File selectors (separate from actions to avoid re-renders)
 export interface FileContextSelectors {
-  // File access - no state dependency, uses ref
+  getFile: (id: FileId) => FileWithId | undefined;
-  getFile: (id: FileId) => File | undefined;
+  getFiles: (ids?: FileId[]) => FileWithId[];
-  getFiles: (ids?: FileId[]) => File[];
-
-  // Record access - uses normalized state
   getFileRecord: (id: FileId) => FileRecord | undefined;
   getFileRecords: (ids?: FileId[]) => FileRecord[];
-
-  // Derived selectors
   getAllFileIds: () => FileId[];
-  getSelectedFiles: () => File[];
+  getSelectedFiles: () => FileWithId[];
   getSelectedFileRecords: () => FileRecord[];
-
-  // Pinned files selectors
   getPinnedFileIds: () => FileId[];
-  getPinnedFiles: () => File[];
+  getPinnedFiles: () => FileWithId[];
   getPinnedFileRecords: () => FileRecord[];
-  isFilePinned: (file: File) => boolean;
+  isFilePinned: (file: FileWithId) => boolean;
-
-  // Stable signature for effect dependencies
   getFilesSignature: () => string;
 }