Repository: Stirling-Tools/Stirling-PDF
File: frontend/src/contexts/file/fileActions.ts (TypeScript)

Code before:
    })),
    thumbnailUrl: thumbnail,
    lastProcessed: Date.now()
  };
}

/**
 * File addition types
 */
type AddFileKind = 'raw' | 'processed' | 'stored';

interface AddFileOptions {
  // For 'raw' files
  files?: File[];

  // For 'processed' files
  filesWithThumbnails?: Array<{ file: File; thumbnail?: string; pageCount?: number }>;

  // For 'stored' files
  filesWithMetadata?: Array<{ file: File; originalId: FileId; metadata: FileMetadata }>;

  // Insertion position
  insertAfterPageId?: string;
}

/**
 * Unified file addition helper - replaces addFiles/addProcessedFiles/addStoredFiles
 */
export async function addFiles(
  kind: AddFileKind,
  options: AddFileOptions,
  stateRef: React.MutableRefObject<FileContextState>,
  filesRef: React.MutableRefObject<Map<FileId, File>>,
  dispatch: React.Dispatch<FileContextAction>,
  lifecycleManager: FileLifecycleManager
): Promise<Array<{ file: File; id: FileId; thumbnail?: string }>> {
  // Acquire mutex to prevent race conditions
  await addFilesMutex.lock();

  try {
  const fileRecords: FileRecord[] = [];
  const addedFiles: Array<{ file: File; id: FileId; thumbnail?: string }> = [];

  // Build quickKey lookup from existing files for deduplication
  const existingQuickKeys = buildQuickKeySet(stateRef.current.files.byId);
  if (DEBUG) console.log(`📄 addFiles(${kind}): Existing quickKeys for deduplication:`, Array.from(existingQuickKeys));

  switch (kind) {
    case 'raw': {
      const { files = [] } = options;
      if (DEBUG) console.log(`📄 addFiles(raw): Adding ${files.length} files with immediate thumbnail generation`);

Review comment (suggestion):
This concerns me, but I don't have a solution to fix for it. 
Its better then an untyped object array having Files and AddedFiles flying around sounds problematic. 

Code after:
    })),
    thumbnailUrl: thumbnail,
    lastProcessed: Date.now()
  };
}

/**
 * File addition types
 */
type AddFileKind = 'raw' | 'processed' | 'stored';

interface AddFileOptions {
  // For 'raw' files
  files?: File[];

  // For 'processed' files
  filesWithThumbnails?: Array<{ file: File; thumbnail?: string; pageCount?: number }>;

  // For 'stored' files
  filesWithMetadata?: Array<{ file: File; originalId: FileId; metadata: FileMetadata }>;

  // Insertion position
  insertAfterPageId?: string;
}

export interface AddedFile {
  file: File;
  id: FileId;
  thumbnail?: string;
}

/**
 * Unified file addition helper - replaces addFiles/addProcessedFiles/addStoredFiles
 */
export async function addFiles(
  kind: AddFileKind,
  options: AddFileOptions,
  stateRef: React.MutableRefObject<FileContextState>,
  filesRef: React.MutableRefObject<Map<FileId, File>>,
  dispatch: React.Dispatch<FileContextAction>,
  lifecycleManager: FileLifecycleManager
): Promise<AddedFile[]> {
  // Acquire mutex to prevent race conditions
  await addFilesMutex.lock();

  try {
  const fileRecords: FileRecord[] = [];
  const addedFiles: AddedFile[] = [];

  // Build quickKey lookup from existing files for deduplication
  const existingQuickKeys = buildQuickKeySet(stateRef.current.files.byId);