🎞️ refactor: Image Rendering with Preview Caching and Layout Reservation (#12114)

* refactor: Update Image Component to Remove Lazy Loading and Enhance Rendering

- Removed the react-lazy-load-image-component dependency from the Image component, simplifying the image loading process.
- Updated the Image component to use a standard <img> tag with async decoding for improved performance and user experience.
- Adjusted related tests to reflect changes in image rendering behavior and ensure proper functionality without lazy loading.

* refactor: Enhance Image Handling and Caching Across Components

- Introduced a new previewCache utility for managing local blob preview URLs, improving image loading efficiency.
- Updated the Image component and related parts (FileRow, Files, Part, ImageAttachment, LogContent) to utilize cached previews, enhancing rendering performance and user experience.
- Added width and height properties to the Image component for better layout management and consistency across different usages.
- Improved file handling logic in useFileHandling to cache previews during file uploads, ensuring quick access to image data.
- Enhanced overall code clarity and maintainability by streamlining image rendering logic and reducing redundancy.

* refactor: Enhance OpenAIImageGen Component with Image Dimensions

- Added width and height properties to the OpenAIImageGen component for improved image rendering and layout management.
- Updated the Image component usage within OpenAIImageGen to utilize the new dimensions, enhancing visual consistency and performance.
- Improved code clarity by destructuring additional properties from the attachment object, streamlining the component's logic.

* refactor: Implement Image Size Caching in DialogImage Component

- Introduced an imageSizeCache to store and retrieve image sizes, enhancing performance by reducing redundant fetch requests.
- Updated the getImageSize function to first check the cache before making network requests, improving efficiency in image handling.
- Added decoding attribute to the image element for optimized rendering behavior.

* refactor: Enhance UserAvatar Component with Avatar Caching and Error Handling

- Introduced avatar caching logic to optimize avatar resolution based on user ID and avatar source, improving performance and reducing redundant image loads.
- Implemented error handling for failed image loads, allowing for fallback to a default avatar when necessary.
- Updated UserAvatar props to streamline the interface by removing the user object and directly accepting avatar-related properties.
- Enhanced overall code clarity and maintainability by refactoring the component structure and logic.

* fix: Layout Shift in Message and Placeholder Components for Consistent Height Management

- Adjusted the height of the PlaceholderRow and related message components to ensure consistent rendering with a minimum height of 31px.
- Updated the MessageParts and ContentRender components to utilize a minimum height for better layout stability.
- Enhanced overall code clarity by standardizing the structure of message-related components.

* tests: Update FileRow Component to Prefer Cached Previews for Image Rendering

- Modified the image URL selection logic in the FileRow component to prioritize cached previews over file paths when uploads are complete, enhancing rendering performance and user experience.
- Updated related tests to reflect changes in image URL handling, ensuring accurate assertions for both preview and file path scenarios.
- Introduced a fallback mechanism to use file paths when no preview exists, improving robustness in file handling.

* fix: Image cache lifecycle and dialog decoding

- Add deletePreview/clearPreviewCache to previewCache.ts for blob URL cleanup
- Wire deletePreview into useFileDeletion to revoke blobs on file delete
- Move dimensionCache.set into useMemo to avoid side effects during render
- Extract IMAGE_MAX_W_PX constant (512) to document coupling with max-w-lg
- Export _resetImageCaches for test isolation
- Change DialogImage decoding from "sync" to "async" to avoid blocking main thread

* fix: Avatar cache invalidation and cleanup

- Include avatarSrc in cache invalidation to prevent stale avatars
- Remove unused username parameter from resolveAvatar
- Skip caching when userId is empty to prevent cache key collisions

* test: Fix test isolation and type safety

- Reset module-level dimensionCache/paintedUrls in beforeEach via _resetImageCaches
- Replace any[] with typed mock signature in cn mock for both test files

* chore: Code quality improvements from review

- Use barrel imports for previewCache in Files.tsx and Part.tsx
- Single Map.get with truthy check instead of has+get in useEventHandlers
- Add JSDoc comments explaining EmptyText margin removal and PlaceholderRow height
- Fix FileRow toast showing "Deleting file" when file isn't actually deleted (progress < 1)

* fix: Address remaining review findings (R1-R3)

- Add deletePreview calls to deleteFiles batch path to prevent blob URL leaks
- Change useFileDeletion import from deep path to barrel (~/utils)
- Change useMemo to useEffect for dimensionCache.set (side effect, not derived value)

* fix: Address audit comments 2, 5, and 7

- Fix files preservation to distinguish null (missing) from [] (empty) in finalHandler
- Add auto-revoke on overwrite in cachePreview to prevent leaked blobs
- Add removePreviewEntry for key transfer without revoke
- Clean up stale temp_file_id cache entry after promotion to permanent file_id

client/src/components/Chat/Input/Files/FileRow.tsx

@@ -3,10 +3,10 @@ import { useToastContext } from '@librechat/client';
 import { EToolResources } from 'librechat-data-provider';
 import type { ExtendedFile } from '~/common';
 import { useDeleteFilesMutation } from '~/data-provider';
+import { logger, getCachedPreview } from '~/utils';
 import { useFileDeletion } from '~/hooks/Files';
 import FileContainer from './FileContainer';
 import { useLocalize } from '~/hooks';
-import { logger } from '~/utils';
 import Image from './Image';
 
 export default function FileRow({
@@ -112,13 +112,15 @@ export default function FileRow({
           )
           .uniqueFiles.map((file: ExtendedFile, index: number) => {
             const handleDelete = () => {
-              showToast({
-                message: localize('com_ui_deleting_file'),
-                status: 'info',
-              });
               if (abortUpload && file.progress < 1) {
                 abortUpload();
               }
+              if (file.progress >= 1) {
+                showToast({
+                  message: localize('com_ui_deleting_file'),
+                  status: 'info',
+                });
+              }
               deleteFile({ file, setFiles });
             };
             const isImage = file.type?.startsWith('image') ?? false;
@@ -134,7 +136,7 @@ export default function FileRow({
               >
                 {isImage ? (
                   <Image
-                    url={file.progress === 1 ? file.filepath : (file.preview ?? file.filepath)}
+                    url={getCachedPreview(file.file_id) ?? file.preview ?? file.filepath}
                     onDelete={handleDelete}
                     progress={file.progress}
                     source={file.source}

client/src/components/Chat/Input/Files/__tests__/FileRow.spec.tsx

@@ -21,6 +21,7 @@ jest.mock('~/utils', () => ({
   logger: {
     log: jest.fn(),
   },
+  getCachedPreview: jest.fn(() => undefined),
 }));
 
 jest.mock('../Image', () => {
@@ -95,7 +96,7 @@ describe('FileRow', () => {
   };
 
   describe('Image URL Selection Logic', () => {
-    it('should use filepath instead of preview when progress is 1 (upload complete)', () => {
+    it('should prefer cached preview over filepath when upload is complete', () => {
       const file = createMockFile({
         file_id: 'uploaded-file',
         preview: 'blob:http://localhost:3080/temp-preview',
@@ -109,8 +110,7 @@ describe('FileRow', () => {
       renderFileRow(filesMap);
 
       const imageUrl = screen.getByTestId('image-url').textContent;
-      expect(imageUrl).toBe('/images/user123/uploaded-file__image.png');
-      expect(imageUrl).not.toContain('blob:');
+      expect(imageUrl).toBe('blob:http://localhost:3080/temp-preview');
     });
 
     it('should use preview when progress is less than 1 (uploading)', () => {
@@ -147,7 +147,7 @@ describe('FileRow', () => {
       expect(imageUrl).toBe('/images/user123/file-without-preview__image.png');
     });
 
-    it('should use filepath when both preview and filepath exist and progress is exactly 1', () => {
+    it('should prefer preview over filepath when both exist and progress is 1', () => {
       const file = createMockFile({
         file_id: 'complete-file',
         preview: 'blob:http://localhost:3080/old-blob',
@@ -161,7 +161,7 @@ describe('FileRow', () => {
       renderFileRow(filesMap);
 
       const imageUrl = screen.getByTestId('image-url').textContent;
-      expect(imageUrl).toBe('/images/user123/complete-file__image.png');
+      expect(imageUrl).toBe('blob:http://localhost:3080/old-blob');
     });
   });
 
@@ -284,7 +284,7 @@ describe('FileRow', () => {
 
       const urls = screen.getAllByTestId('image-url').map((el) => el.textContent);
       expect(urls).toContain('blob:http://localhost:3080/preview-1');
-      expect(urls).toContain('/images/user123/file-2__image.png');
+      expect(urls).toContain('blob:http://localhost:3080/preview-2');
     });
 
     it('should deduplicate files with the same file_id', () => {
@@ -321,10 +321,10 @@ describe('FileRow', () => {
     });
   });
 
-  describe('Regression: Blob URL Bug Fix', () => {
-    it('should NOT use revoked blob URL after upload completes', () => {
+  describe('Preview Cache Integration', () => {
+    it('should prefer preview blob URL over filepath for zero-flicker rendering', () => {
       const file = createMockFile({
-        file_id: 'regression-test',
+        file_id: 'cache-test',
         preview: 'blob:http://localhost:3080/d25f730c-152d-41f7-8d79-c9fa448f606b',
         filepath:
           '/images/68c98b26901ebe2d87c193a2/c0fe1b93-ba3d-456c-80be-9a492bfd9ed0__image.png',
@@ -337,8 +337,24 @@ describe('FileRow', () => {
       renderFileRow(filesMap);
 
       const imageUrl = screen.getByTestId('image-url').textContent;
+      expect(imageUrl).toBe('blob:http://localhost:3080/d25f730c-152d-41f7-8d79-c9fa448f606b');
+    });
 
-      expect(imageUrl).not.toContain('blob:');
+    it('should fall back to filepath when no preview exists', () => {
+      const file = createMockFile({
+        file_id: 'no-preview',
+        preview: undefined,
+        filepath:
+          '/images/68c98b26901ebe2d87c193a2/c0fe1b93-ba3d-456c-80be-9a492bfd9ed0__image.png',
+        progress: 1,
+      });
+
+      const filesMap = new Map<string, ExtendedFile>();
+      filesMap.set(file.file_id, file);
+
+      renderFileRow(filesMap);
+
+      const imageUrl = screen.getByTestId('image-url').textContent;
       expect(imageUrl).toBe(
         '/images/68c98b26901ebe2d87c193a2/c0fe1b93-ba3d-456c-80be-9a492bfd9ed0__image.png',
       );