fix:Fix a Type error

fix:Fix the issue of failing to join room with simple IDs

README.md

@@ -41,11 +41,12 @@ We believe everyone should have control over their own data. PrivyDrop was creat
 
 Before you begin, ensure your development environment has [Node.js](https://nodejs.org/) (v18+), [npm](https://www.npmjs.com/), and a running [Redis](https://redis.io/) instance installed.
 
-1.  **Clone the Project**
+1.  **Clone the Project & install redis**
 
     ```bash
     git clone https://github.com/david-bai00/PrivyDrop.git
     cd PrivyDrop
+    sudo apt-get install -y redis-server
     ```
 
 2.  **Configure and Start the Backend Service**
@@ -66,7 +67,7 @@ Before you begin, ensure your development environment has [Node.js](https://node
     cd frontend
     pnpm install
 
-    # Copy the development environment file, then modify .env.development as needed
+    # Copy the development environment file, then modify .env.development as needed, Remove optional items
     cp .env_development_example .env.development
 
     pnpm dev # Starts by default at http://localhost:3002

README.zh-CN.md

@@ -41,11 +41,12 @@ PrivyDrop (原 SecureShare) 是一个基于 WebRTC 的开源点对点（P2P）
 
 在开始之前，请确保你的开发环境已安装 [Node.js](https://nodejs.org/) (v18+), [npm](https://www.npmjs.com/) 以及一个正在运行的 [Redis](https://redis.io/) 实例。
 
-1.  **克隆项目**
+1.  **克隆项目 & 安装 redis**
 
     ```bash
     git clone https://github.com/david-bai00/PrivyDrop.git
-    cd privydrop
+    cd PrivyDrop
+    sudo apt-get install -y redis-server
     ```
 
 2.  **配置并启动后端服务**
@@ -66,7 +67,7 @@ PrivyDrop (原 SecureShare) 是一个基于 WebRTC 的开源点对点（P2P）
     cd frontend
     pnpm install
 
-    # 复制开发环境变量文件，然后根据需要修改 .env.development
+    # 复制开发环境变量文件，然后根据需要修改 .env.development，删除可选项
     cp .env_development_example .env.development
 
     pnpm dev # 默认启动于 http://localhost:3002

frontend/.env_development_example

@@ -1,4 +1,4 @@
-NEXT_PUBLIC_API_URL=http://43.142.81.156:3001
+NEXT_PUBLIC_API_URL=http://localhost:3001
 
 # Option,Delete if not needed
 NEXT_PUBLIC_TURN_HOST=43.142.81.156

frontend/app/config/environment.ts

@@ -11,29 +11,43 @@ export const config = {
 };
 
 export const getIceServers = () => {
-  // Default public STUN server
-  const iceServers: RTCIceServer[] = [
-    {
+  const iceServers: RTCIceServer[] = [];
+
+  if (config.USE_HTTPS) {
+    // Check if TURN server configuration is complete
+    if (!config.TURN_HOST || !config.TURN_USERNAME || !config.TURN_CREDENTIAL) {
+      console.warn(
+        "TURN server configuration incomplete in HTTPS environment. " +
+        "Please set NEXT_PUBLIC_TURN_HOST, NEXT_PUBLIC_TURN_USERNAME, and NEXT_PUBLIC_TURN_PASSWORD " +
+        "environment variables for better connectivity. Falling back to Google STUN server."
+      );
+      
+      // Fallback to Google STUN server
+      iceServers.push({
+        urls: "stun:stun.l.google.com:19302",
+      });
+    } else {
+      // Add self-hosted STUN and TURN servers
+      iceServers.push(
+        {
+          urls: `stun:${config.TURN_HOST}:3478`,
+        },
+        {
+          urls: `turns:${config.TURN_HOST}:443`,
+          username: config.TURN_USERNAME,
+          credential: config.TURN_CREDENTIAL,
+        },
+        {
+          urls: `turn:${config.TURN_HOST}:3478`,
+          username: config.TURN_USERNAME,
+          credential: config.TURN_CREDENTIAL,
+        }
+      );
+    }
+  } else {
+    // Development environment uses Google's public STUN server
+    iceServers.push({
       urls: "stun:stun.l.google.com:19302",
-    },
-  ];
-
-  // Add self-hosted TURN/STUN server if configured through environment variables
-  if (config.TURN_HOST && config.TURN_USERNAME && config.TURN_CREDENTIAL) {
-    const turnUrls = config.USE_HTTPS
-      ? [`turns:${config.TURN_HOST}:443`, `turn:${config.TURN_HOST}:3478`]
-      : [`turn:${config.TURN_HOST}:3478`];
-
-    // Add STUN from the self-hosted server
-    iceServers.push({
-      urls: `stun:${config.TURN_HOST}:3478`,
-    });
-
-    // Add TURN from the self-hosted server
-    iceServers.push({
-      urls: turnUrls,
-      username: config.TURN_USERNAME,
-      credential: config.TURN_CREDENTIAL,
     });
   }
 

frontend/components/ClipboardApp.tsx

@@ -51,40 +51,15 @@ const ClipboardApp = () => {
 
   // 简化的 WebRTC 连接初始化
   const {
-    sharePeerCount,
-    retrievePeerCount,
-    broadcastDataToAllPeers,
     requestFile,
     requestFolder,
     setReceiverDirectoryHandle,
     getReceiverSaveType,
-    senderDisconnected,
-    resetReceiverConnection,
-    resetSenderConnection,
-    manualSafeSave,
   } = useWebRTCConnection({
     messages,
     putMessageInMs,
   });
 
-  const resetAppState = useCallback(async () => {
-    try {
-      // Reset file transfer state
-      useFileTransferStore.getState().resetReceiverState();
-
-      // Reset WebRTC connection state
-      await resetReceiverConnection();
-
-      // Reset room input
-      setRetrieveRoomIdInput("");
-
-      console.log("Application state reset successfully");
-    } catch (error) {
-      console.error("Error during state reset:", error);
-      window.location.reload();
-    }
-  }, [resetReceiverConnection, setRetrieveRoomIdInput]);
-
   // 大大简化的房间管理 - 不再需要传递任何 WebRTC 依赖
   const {
     processRoomIdInput,
@@ -243,7 +218,6 @@ const ClipboardApp = () => {
               getReceiverSaveType={getReceiverSaveType}
               retrieveMessage={retrieveMessage}
               handleLeaveRoom={handleLeaveReceiverRoom}
-              manualSafeSave={manualSafeSave}
             />
           )}
         </CardContent>

frontend/components/ClipboardApp/FileListDisplay.tsx

@@ -11,6 +11,9 @@ import { getDictionary } from "@/lib/dictionary";
 import { useLocale } from "@/hooks/useLocale";
 import type { Messages } from "@/types/messages";
 import { useFileTransferStore } from "@/stores/fileTransferStore";
+import { supportsAutoDownload } from "@/lib/browserUtils";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
 
 function formatFolderDis(template: string, num: number, size: string) {
   return template.replace("{num}", num.toString()).replace("{size}", size);
@@ -41,7 +44,6 @@ interface FileListDisplayProps {
   onRequest?: (item: FileMeta) => void; // Request file
   onDelete?: (item: FileMeta) => void;
   onLocationPick?: () => Promise<boolean>;
-  onSafeSave?: () => void; // New prop for safe save functionality
   saveType?: { [fileId: string]: boolean }; // File stored on disk or in memory
   largeFileThreshold?: number;
 }
@@ -63,14 +65,13 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
   onRequest,
   onDelete,
   onLocationPick,
-  onSafeSave,
   saveType,
   largeFileThreshold = 500 * 1024 * 1024, // 500MB default
 }) => {
   const locale = useLocale();
   const [messages, setMessages] = useState<Messages | null>(null);
 
-  // 获取store的清理方法
+  // Get the cleaning method of the store
   const { clearSendProgress, clearReceiveProgress } = useFileTransferStore();
   const [showFinished, setShowFinished] = useState<{
     [fileId: string]: boolean;
@@ -78,6 +79,11 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
   // Add a ref to store the previous showFinished state
   const prevShowFinishedRef = useRef<{ [fileId: string]: boolean }>({});
 
+  // Add save pending status - Used for manual saving on non-Chrome browsers
+  const [pendingSave, setPendingSave] = useState<{
+    [fileId: string]: boolean;
+  }>({});
+
   const [pickedLocation, setPickedLocation] = useState<boolean>(false); // Whether a save directory has been selected
   const [needPickLocation, setNeedPickLocation] = useState<boolean>(false); // Whether a save directory needs to be selected -- for large files, folders, or user choice
 
@@ -92,6 +98,19 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
     [fileId: string]: number;
   }>({});
 
+  // Handling manual save - for non-Chrome browsers
+  const handleManualSave = (item: FileMeta) => {
+    if (onDownload) {
+      onDownload(item);
+      // Clear the pending save state to display UI as "Completed"
+      setPendingSave((prev) => {
+        const updated = { ...prev };
+        delete updated[item.fileId];
+        return updated;
+      });
+    }
+  };
+
   useEffect(() => {
     getDictionary(locale)
       .then((dict) => setMessages(dict))
@@ -185,7 +204,7 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
               delete updated[fileId];
               return updated;
             });
-            // 根据模式清理对应的progress数据
+            // Clean the corresponding progress data according to the pattern
             if (mode === "sender") {
               clearSendProgress(fileId, activePeerId);
             } else {
@@ -228,7 +247,6 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
       const prevShowFinished = prevShowFinishedRef.current[item.fileId];
       const isSaveToDisk = saveType ? saveType[item.fileId] : false;
 
-      // 添加详细调试信息
       const fileProgress = fileProgresses[item.fileId];
       const activePeerId = activeTransfers[item.fileId];
       const currentProgress = activePeerId
@@ -237,10 +255,37 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
       // Detecting false -> true transitions
       if (!prevShowFinished && currentShowFinished) {
         if (!isSaveToDisk && onDownload) {
-          onDownload(item);
+          const isAutoDownloadSupported = supportsAutoDownload();
+
+          if (isAutoDownloadSupported) {
+            // Browsers that support automatic downloads like Chrome: Download directly
+            if (developmentEnv === "development") {
+              postLogToBackend(
+                `[Download Debug] Auto-downloading file: ${item.name}`
+              );
+            }
+            onDownload(item);
+          } else {
+            // Non-Chrome browsers: Set to save status, wait for user manual click
+            if (developmentEnv === "development") {
+              postLogToBackend(
+                `[Download Debug] Setting pendingSave for non-Chrome browser: ${item.name}`
+              );
+            }
+            setPendingSave((prev) => ({
+              ...prev,
+              [item.fileId]: true,
+            }));
+          }
+        } else {
+          if (developmentEnv === "development") {
+            postLogToBackend(
+              `Skipping download logic - isSaveToDisk: ${isSaveToDisk}, onDownload: ${!!onDownload}`
+            );
+          }
         }
 
-        // Increase download count - 文件传输完成时增加下载次数 (只计算一次)
+        // Increase download count - Increment download count upon completion of file transfer (counted only once)
         setDownloadCounts((prevCounts) => ({
           ...prevCounts,
           [item.fileId]: (prevCounts[item.fileId] || 0) + 1,
@@ -250,22 +295,17 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
       // Update the last status
       prevShowFinishedRef.current[item.fileId] = currentShowFinished;
     });
-  }, [
-    showFinished,
-    singleFiles,
-    folders,
-    saveType,
-    onDownload,
-    downloadCounts,
-  ]);
+  }, [showFinished, singleFiles, folders, saveType, onDownload]);
 
   //Actions corresponding to each file - progress, download, delete
   const renderItemActions = (item: FileMeta) => {
     const fileProgress = fileProgresses[item.fileId];
     const activePeerId = activeTransfers[item.fileId];
     const progress = activePeerId ? fileProgress?.[activePeerId] : null;
-    const showCompletion = showFinished[item.fileId];
+    const showCompletion =
+      showFinished[item.fileId] && !pendingSave[item.fileId]; // Only display completed when the transfer is finished and not in the save pending state
     const isSaveToDisk = saveType ? saveType[item.fileId] : false;
+    const isPendingSave = pendingSave[item.fileId] || false;
     // Get download count
     const downloadCount = downloadCounts[item.fileId] || 0;
 
@@ -297,6 +337,7 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
             onDownload && ( //Request && Download
               <FileTransferButton
                 onRequest={() => onRequest(item)}
+                onSave={() => handleManualSave(item)}
                 isCurrentFileTransferring={
                   progress
                     ? progress.progress > 0 && progress.progress < 1
@@ -304,6 +345,7 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
                 }
                 isOtherFileTransferring={isAnyFileTransferring && !progress}
                 isSavedToDisk={saveType ? saveType[item.fileId] : false}
+                isPendingSave={isPendingSave}
               />
             )}
           {/* display download Num*/}
@@ -415,29 +457,6 @@ const FileListDisplay: React.FC<FileListDisplayProps> = ({
                     {messages.text.FileListDisplay.chooseSavePath_dis}
                   </Button>
                 )}
-                {/* Safe Save Button - only show when location is picked and files are saved to disk */}
-                {onSafeSave &&
-                  pickedLocation &&
-                  (isAnyFileTransferring ||
-                    (saveType &&
-                      Object.values(saveType).some(
-                        (isSavedToDisk) => isSavedToDisk
-                      ))) && (
-                    <Tooltip
-                      content={messages.text.FileListDisplay.safeSave_tooltip}
-                    >
-                      <Button
-                        onClick={() => {
-                          onSafeSave();
-                        }}
-                        variant="outline"
-                        size="sm"
-                        className="mr-2 text-green-600 border-green-600 hover:bg-green-50"
-                      >
-                        {messages.text.FileListDisplay.safeSave_dis}
-                      </Button>
-                    </Tooltip>
-                  )}
               </div>
             </div>
           )}

frontend/components/ClipboardApp/FileTransferButton.tsx

@@ -13,22 +13,28 @@ import type { Messages } from "@/types/messages";
 
 interface FileTransferButtonProps {
   onRequest: () => void;
+  onSave?: () => void; // 新增：处理手动保存
   isCurrentFileTransferring: boolean;
   isOtherFileTransferring: boolean;
   isSavedToDisk: boolean;
+  isPendingSave?: boolean; // 新增：是否待保存状态
 }
 // Manage buttons for different download statuses
 const FileTransferButton = ({
   onRequest,
+  onSave,
   isCurrentFileTransferring,
   isOtherFileTransferring,
   isSavedToDisk,
+  isPendingSave = false,
 }: FileTransferButtonProps) => {
   const locale = useLocale();
   const [messages, setMessages] = useState<Messages | null>(null);
-  // Button status judgment
+  // Button status judgment - 待保存状态时按钮应该可点击
   const isDisabled =
-    isCurrentFileTransferring || isSavedToDisk || isOtherFileTransferring;
+    isCurrentFileTransferring ||
+    isSavedToDisk ||
+    (isOtherFileTransferring && !isPendingSave);
 
   useEffect(() => {
     getDictionary(locale)
@@ -41,6 +47,8 @@ const FileTransferButton = ({
       return messages!.text.FileTransferButton.SavedToDisk_tips;
     if (isCurrentFileTransferring)
       return messages!.text.FileTransferButton.CurrentFileTransferring_tips;
+    if (isPendingSave)
+      return messages!.text.FileTransferButton.PendingSave_tips;
     if (isOtherFileTransferring)
       return messages!.text.FileTransferButton.OtherFileTransferring_tips;
     return messages!.text.FileTransferButton.download_tips;
@@ -60,6 +68,12 @@ const FileTransferButton = ({
         className: "mr-2 cursor-not-allowed",
       };
     }
+    if (isPendingSave) {
+      return {
+        variant: "default" as const, // 使用更明显的样式
+        className: "mr-2 bg-green-600 hover:bg-green-700 text-white",
+      };
+    }
     if (isOtherFileTransferring) {
       return {
         variant: "outline" as const,
@@ -83,7 +97,7 @@ const FileTransferButton = ({
         <TooltipTrigger asChild>
           <span className="inline-block">
             <Button
-              onClick={onRequest}
+              onClick={isPendingSave && onSave ? onSave : onRequest}
               variant={buttonStyles.variant}
               size="sm"
               className={buttonStyles.className}
@@ -91,11 +105,13 @@ const FileTransferButton = ({
             >
               <Download
                 className={`mr-2 h-4 w-4 ${
-                  isOtherFileTransferring ? "opacity-50" : ""
+                  isOtherFileTransferring && !isPendingSave ? "opacity-50" : ""
                 }`}
               />
               {isSavedToDisk
                 ? messages.text.FileTransferButton.Saved_dis
+                : isPendingSave
+                ? messages.text.FileTransferButton.Save_dis
                 : isOtherFileTransferring
                 ? messages.text.FileTransferButton.Waiting_dis
                 : messages.text.FileTransferButton.Download_dis}

frontend/components/ClipboardApp/RetrieveTabPanel.tsx

@@ -1,7 +1,6 @@
 import React, { useCallback } from "react";
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
-import RichTextEditor from "@/components/Editor/RichTextEditor";
 import {
   ReadClipboardButton,
   WriteClipboardButton,
@@ -9,7 +8,6 @@ import {
 import FileListDisplay from "@/components/ClipboardApp/FileListDisplay";
 import type { Messages } from "@/types/messages";
 import type { FileMeta } from "@/types/webrtc";
-import type { ProgressState } from "@/hooks/useWebRTCConnection"; // Assuming this type is exported
 
 import { useFileTransferStore } from "@/stores/fileTransferStore";
 
@@ -32,7 +30,6 @@ interface RetrieveTabPanelProps {
     directoryHandle: FileSystemDirectoryHandle
   ) => Promise<void>;
   getReceiverSaveType: () => { [fileId: string]: boolean } | undefined;
-  manualSafeSave: () => void; // Add manual safe save function
   retrieveMessage: string;
   handleLeaveRoom: () => void;
 }
@@ -49,11 +46,10 @@ export function RetrieveTabPanel({
   requestFolder,
   setReceiverDirectoryHandle,
   getReceiverSaveType,
-  manualSafeSave,
   retrieveMessage,
   handleLeaveRoom,
 }: RetrieveTabPanelProps) {
-  // 从 store 中获取状态
+  // Get the status from the store
   const {
     retrieveRoomStatusText,
     retrieveRoomIdInput,
@@ -61,38 +57,25 @@ export function RetrieveTabPanel({
     retrievedFileMetas,
     receiveProgress,
     isAnyFileTransferring,
-    senderDisconnected,
     isReceiverInRoom,
   } = useFileTransferStore();
 
   const onLocationPick = useCallback(async (): Promise<boolean> => {
     if (!messages) return false; // Should not happen if panel is rendered
     if (!window.showDirectoryPicker) {
-      putMessageInMs(
-        // messages.text.ClipboardApp.pickSaveUnsupported ||
-        "Directory picker not supported.",
-        false
-      );
+      putMessageInMs(messages.text.ClipboardApp.pickSaveUnsupported, false);
       return false;
     }
     if (!window.confirm(messages.text.ClipboardApp.pickSaveMsg)) return false;
     try {
       const directoryHandle = await window.showDirectoryPicker();
       await setReceiverDirectoryHandle(directoryHandle);
-      putMessageInMs(
-        // messages.text.ClipboardApp.pickSaveSuccess ||
-        "Save location set.",
-        false
-      );
+      putMessageInMs(messages.text.ClipboardApp.pickSaveSuccess, false);
       return true;
     } catch (err: any) {
       if (err.name !== "AbortError") {
         console.error("Failed to set up folder receive:", err);
-        putMessageInMs(
-          // messages.text.ClipboardApp.pickSaveError ||
-          "Could not set save location.",
-          false
-        );
+        putMessageInMs(messages.text.ClipboardApp.pickSaveError, false);
       }
       return false;
     }
@@ -151,12 +134,14 @@ export function RetrieveTabPanel({
             {messages.text.ClipboardApp.html.joinRoom_dis}
           </Button>
           <Button
-            variant="outline"
+            variant={isAnyFileTransferring ? "destructive" : "outline"}
             onClick={handleLeaveRoom}
-            disabled={!isReceiverInRoom || isAnyFileTransferring}
+            disabled={!isReceiverInRoom}
             className="w-full sm:w-auto px-4 order-2"
           >
-            {messages.text.ClipboardApp.roomStatus.leaveRoomBtn}
+            {isAnyFileTransferring
+              ? messages.text.ClipboardApp.roomStatus.leaveRoomBtn + " ⚠️"
+              : messages.text.ClipboardApp.roomStatus.leaveRoomBtn}
           </Button>
         </div>
       </div>
@@ -181,7 +166,6 @@ export function RetrieveTabPanel({
         onDownload={handleDownloadFile}
         onRequest={handleFileRequestFromPanel} // Use the panel's own handler
         onLocationPick={onLocationPick} // Use the panel's own handler
-        onSafeSave={manualSafeSave} // Add safe save handler
         saveType={getReceiverSaveType()}
       />
       {retrieveMessage && (

frontend/components/ClipboardApp/SendTabPanel.tsx

@@ -11,7 +11,6 @@ import FileListDisplay from "@/components/ClipboardApp/FileListDisplay";
 import AnimatedButton from "@/components/ui/AnimatedButton";
 import type { Messages } from "@/types/messages";
 import type { CustomFile, FileMeta } from "@/types/webrtc";
-import type { ProgressState } from "@/hooks/useWebRTCConnection";
 
 import { useFileTransferStore } from "@/stores/fileTransferStore";
 
@@ -55,7 +54,7 @@ export function SendTabPanel({
   currentValidatedShareRoomId,
   handleLeaveSenderRoom,
 }: SendTabPanelProps) {
-  // 从 store 中获取状态
+  // Get the status from the store
   const {
     shareContent,
     sendFiles,
@@ -68,6 +67,8 @@ export function SendTabPanel({
   const [inputFieldValue, setInputFieldValue] = useState<string>(
     currentValidatedShareRoomId
   );
+  // State to track ID generation mode (false = will show simple next, true = will show random next)
+  const [isSimpleIdMode, setIsSimpleIdMode] = useState<boolean>(true);
 
   // When the validatedShareRoomId from the parent component changes (e.g., after initial fetch), synchronize the local input field's value
   useEffect(() => {
@@ -92,6 +93,40 @@ export function SendTabPanel({
     [processRoomIdInput]
   );
 
+  // Handle ID generation toggle
+  const handleIdGeneration = useCallback(async () => {
+    if (isSimpleIdMode) {
+      // Generate random UUID
+      const randomId = crypto.randomUUID();
+      processRoomIdInput(randomId);
+    } else {
+      // Generate simple 4-digit ID by calling backend API
+      try {
+        const { fetchRoom } = await import("@/app/config/api");
+        const simpleRoomId = await fetchRoom();
+        if (simpleRoomId) {
+          // fetchRoom() already created the room, so set it as initial room ID
+          // This prevents joinRoom() from trying to create it again
+          setInputFieldValue(simpleRoomId);
+          const { useFileTransferStore } = await import(
+            "@/stores/fileTransferStore"
+          );
+          const store = useFileTransferStore.getState();
+          store.setShareRoomId(simpleRoomId);
+          // IMPORTANT: Set as initial room ID to prevent duplicate creation
+          store.setInitShareRoomId(simpleRoomId);
+        } else {
+          processRoomIdInput(crypto.randomUUID());
+        }
+      } catch (error) {
+        processRoomIdInput(crypto.randomUUID());
+      }
+    }
+
+    // Toggle mode for next click
+    setIsSimpleIdMode(!isSimpleIdMode);
+  }, [isSimpleIdMode, processRoomIdInput, setInputFieldValue]);
+
   return (
     <div id="send-panel" role="tabpanel" aria-labelledby="send-tab">
       <div className="mb-3 text-sm text-gray-600">
@@ -141,10 +176,12 @@ export function SendTabPanel({
             <Button
               variant="outline"
               className="w-full sm:w-auto px-4"
-              onClick={() => processRoomIdInput(crypto.randomUUID())}
+              onClick={handleIdGeneration}
               disabled={isSenderInRoom}
             >
-              {messages.text.ClipboardApp.html.generateRoomId_tips}
+              {isSimpleIdMode
+                ? messages.text.ClipboardApp.html.generateRandomId_tips
+                : messages.text.ClipboardApp.html.generateSimpleId_tips}
             </Button>
             <Button
               className="w-full sm:w-auto px-4"
@@ -174,12 +211,14 @@ export function SendTabPanel({
             {messages.text.ClipboardApp.html.SyncSending_dis}
           </AnimatedButton>
           <Button
-            variant="outline"
+            variant={isAnyFileTransferring ? "destructive" : "outline"}
             onClick={handleLeaveSenderRoom}
-            disabled={!isSenderInRoom || isAnyFileTransferring}
+            disabled={!isSenderInRoom}
             className="w-full sm:w-auto px-4 order-2"
           >
-            {messages.text.ClipboardApp.roomStatus.leaveRoomBtn}
+            {isAnyFileTransferring
+              ? messages.text.ClipboardApp.roomStatus.leaveRoomBtn + " ⚠️"
+              : messages.text.ClipboardApp.roomStatus.leaveRoomBtn}
           </Button>
         </div>
       </div>

frontend/constants/messages/de.ts

@@ -235,9 +235,11 @@ export const de: Messages = {
       OtherFileTransferring_tips:
         "Bitte warten Sie, bis die aktuelle Übertragung abgeschlossen ist",
       download_tips: "Klicken Sie, um die Datei herunterzuladen",
+      PendingSave_tips: "Klicken Sie, um die Datei lokal zu speichern", // 新增
       Saved_dis: "Gespeichert",
       Waiting_dis: "Warten",
       Download_dis: "Herunterladen",
+      Save_dis: "Speichern", // 新增
     },
     FileListDisplay: {
       sending_dis: "Senden",
@@ -254,11 +256,6 @@ export const de: Messages = {
       chooseSavePath_tips:
         "Speichern Sie große Dateien oder Ordner direkt in einem ausgewählten Verzeichnis. 👉",
       chooseSavePath_dis: "Speicherort auswählen",
-      safeSave_dis: "Sicheres Speichern",
-      safeSave_tooltip:
-        "Keine Angst vor Verbindungsunterbrechung, klicken Sie hier, um Dateien sicher zu speichern für die nächste Fortsetzung",
-      safeSaveSuccessMsg:
-        "Dateien wurden sicher auf der Festplatte gespeichert, sicher die Seite zu schließen, unterstützt Wiederaufnahme der Übertragung!",
     },
     RetrieveMethod: {
       P: "Glückwunsch 🎉 Freigegebene Inhalte warten darauf, abgerufen zu werden:",
@@ -296,6 +293,9 @@ export const de: Messages = {
         failMsg: "Fehler beim Beitreten zum Raum:",
       },
       pickSaveMsg: "Direkt auf Festplatte speichern?",
+      pickSaveUnsupported: "Verzeichnisauswahl nicht unterstützt.",
+      pickSaveSuccess: "Speicherort festgelegt.",
+      pickSaveError: "Speicherort konnte nicht festgelegt werden.",
       roomStatus: {
         senderEmptyMsg: "Raum ist leer",
         receiverEmptyMsg:
@@ -311,6 +311,9 @@ export const de: Messages = {
       noFilesForFolderMsg: "Keine Dateien im Ordner '{folderName}' gefunden.",
       zipError: "Fehler beim Erstellen der ZIP-Datei.",
       fileNotFoundMsg: "Datei '{fileName}' zum Herunterladen nicht gefunden.",
+      confirmLeaveWhileTransferring:
+        "Dateien werden derzeit übertragen. Das Verlassen wird die Übertragung unterbrechen. Sind Sie sicher?",
+      leaveWhileTransferringSuccess: "Raum verlassen, Übertragung unterbrochen",
       html: {
         senderTab: "Senden",
         retrieveTab: "Abrufen",
@@ -321,7 +324,8 @@ export const de: Messages = {
         Copy_dis: "Kopieren",
         inputRoomIdprompt: "Ihre Raum-ID (bearbeitbar):",
         joinRoomBtn: "Raum beitreten",
-        generateRoomId_tips: "Zufällige ID",
+        generateSimpleId_tips: "Einfache ID",
+        generateRandomId_tips: "Zufällige ID",
         readClipboardToRoomId: "Raum-ID einfügen",
         enterRoomID_placeholder: "Raum-ID eingeben",
         retrieveMethod: "Abrufmethode",

frontend/constants/messages/en.ts

@@ -232,9 +232,11 @@ export const en: Messages = {
       OtherFileTransferring_tips:
         "Please wait for current transfer to complete",
       download_tips: "Click to download file",
+      PendingSave_tips: "Click to save file locally",
       Saved_dis: "Saved",
       Waiting_dis: "Waiting",
       Download_dis: "Download",
+      Save_dis: "Save",
     },
     FileListDisplay: {
       sending_dis: "Sending",
@@ -251,11 +253,6 @@ export const en: Messages = {
       chooseSavePath_tips:
         "Save large files or folders directly to a selected directory. 👉",
       chooseSavePath_dis: "Choose save location",
-      safeSave_dis: "Safe Save",
-      safeSave_tooltip:
-        "Don't worry about connection interruption, click here to safely save files for next resume",
-      safeSaveSuccessMsg:
-        "Files have been safely saved to disk, safe to close page, supports resume transfer!",
     },
     RetrieveMethod: {
       P: "Congrats 🎉 Share content is waiting to be retrieved:",
@@ -289,6 +286,9 @@ export const en: Messages = {
         failMsg: "Failed to join room:",
       },
       pickSaveMsg: "Save Directly to Disk ?",
+      pickSaveUnsupported: "Directory picker not supported.",
+      pickSaveSuccess: "Save location set.",
+      pickSaveError: "Could not set save location.",
       roomStatus: {
         senderEmptyMsg: "Room is empty",
         receiverEmptyMsg: "You can accept an invitation to join the room",
@@ -303,6 +303,8 @@ export const en: Messages = {
       noFilesForFolderMsg: "No files found for folder '{folderName}'.",
       zipError: "Error creating ZIP.",
       fileNotFoundMsg: "File '{fileName}' not found for download.",
+      confirmLeaveWhileTransferring: "Files are currently transferring. Leaving will interrupt the transfer. Are you sure?",
+      leaveWhileTransferringSuccess: "Left room, transfer interrupted",
       html: {
         senderTab: "Send",
         retrieveTab: "Retrieve",
@@ -313,7 +315,8 @@ export const en: Messages = {
         Copy_dis: "Copy",
         inputRoomIdprompt: "Your RoomID (Editable):",
         joinRoomBtn: "Join room",
-        generateRoomId_tips: "Random ID",
+        generateSimpleId_tips: "Simple ID",
+        generateRandomId_tips: "Random ID",
         readClipboardToRoomId: "Paste RoomID",
         enterRoomID_placeholder: "enter RoomID",
         retrieveMethod: "Retrieve method",

frontend/constants/messages/es.ts

@@ -233,9 +233,11 @@ export const es: Messages = {
       OtherFileTransferring_tips:
         "Por favor espera a que se complete la transferencia actual",
       download_tips: "Haz clic para descargar el archivo",
+      PendingSave_tips: "Haz clic para guardar el archivo localmente", // 新增
       Saved_dis: "Guardado",
       Waiting_dis: "Esperando",
       Download_dis: "Descargar",
+      Save_dis: "Guardar", // 新增
     },
     FileListDisplay: {
       sending_dis: "Enviando",
@@ -252,11 +254,6 @@ export const es: Messages = {
       chooseSavePath_tips:
         "Guarda archivos grandes o carpetas directamente en un directorio seleccionado. 👉",
       chooseSavePath_dis: "Elegir ubicación de guardado",
-      safeSave_dis: "Guardar Seguro",
-      safeSave_tooltip:
-        "No te preocupes por la interrupción de la conexión, haz clic aquí para guardar archivos de forma segura para la próxima reanudación",
-      safeSaveSuccessMsg:
-        "Los archivos se han guardado de forma segura en el disco, es seguro cerrar la página, ¡admite transferencia de reanudación!",
     },
     RetrieveMethod: {
       P: "¡Felicitaciones 🎉 El contenido compartido está esperando ser recuperado:",
@@ -290,6 +287,9 @@ export const es: Messages = {
         failMsg: "Error al unirse a la sala:",
       },
       pickSaveMsg: "¿Guardar Directamente en Disco?",
+      pickSaveUnsupported: "Selector de directorio no compatible.",
+      pickSaveSuccess: "Ubicación de guardado establecida.",
+      pickSaveError: "No se pudo establecer la ubicación de guardado.",
       roomStatus: {
         senderEmptyMsg: "La sala está vacía",
         receiverEmptyMsg: "Puedes aceptar una invitación para unirte a la sala",
@@ -305,6 +305,10 @@ export const es: Messages = {
         "No se encontraron archivos en la carpeta '{folderName}'.",
       zipError: "Error al crear el archivo ZIP.",
       fileNotFoundMsg: "Archivo '{fileName}' no encontrado para descargar.",
+      confirmLeaveWhileTransferring:
+        "Los archivos se están transfiriendo actualmente. Salir interrumpirá la transferencia. ¿Estás seguro?",
+      leaveWhileTransferringSuccess:
+        "Saliste de la sala, transferencia interrumpida",
       html: {
         senderTab: "Enviar",
         retrieveTab: "Recuperar",
@@ -315,7 +319,8 @@ export const es: Messages = {
         Copy_dis: "Copiar",
         inputRoomIdprompt: "Tu ID de Sala (Editable):",
         joinRoomBtn: "Unirse a sala",
-        generateRoomId_tips: "ID Aleatorio",
+        generateSimpleId_tips: "ID Simple",
+        generateRandomId_tips: "ID Aleatorio",
         readClipboardToRoomId: "Pegar ID de Sala",
         enterRoomID_placeholder: "ingresa ID de Sala",
         retrieveMethod: "Método de recuperación",

frontend/constants/messages/fr.ts

@@ -236,9 +236,11 @@ export const fr: Messages = {
       OtherFileTransferring_tips:
         "Veuillez attendre que le transfert actuel soit terminé",
       download_tips: "Cliquez pour télécharger le fichier",
+      PendingSave_tips: "Cliquez pour enregistrer le fichier localement", // 新增
       Saved_dis: "Enregistré",
       Waiting_dis: "En attente",
       Download_dis: "Télécharger",
+      Save_dis: "Enregistrer", // 新增
     },
     FileListDisplay: {
       sending_dis: "Envoi",
@@ -255,11 +257,6 @@ export const fr: Messages = {
       chooseSavePath_tips:
         "Enregistrez des fichiers volumineux ou des dossiers directement dans un répertoire sélectionné. 👉",
       chooseSavePath_dis: "Choisir l'emplacement de sauvegarde",
-      safeSave_dis: "Sauvegarde Sécurisée",
-      safeSave_tooltip:
-        "N'ayez pas peur de l'interruption de connexion, cliquez ici pour sauvegarder les fichiers en toute sécurité pour la prochaine reprise",
-      safeSaveSuccessMsg:
-        "Les fichiers ont été sauvegardés en toute sécurité sur le disque, sûr de fermer la page, prend en charge la reprise du transfert !",
     },
     RetrieveMethod: {
       P: "Félicitations 🎉 Le contenu partagé attend d'être récupéré :",
@@ -296,6 +293,9 @@ export const fr: Messages = {
         failMsg: "Échec de la connexion à la salle :",
       },
       pickSaveMsg: "Enregistrer directement sur le disque ?",
+      pickSaveUnsupported: "Sélecteur de répertoire non pris en charge.",
+      pickSaveSuccess: "Emplacement de sauvegarde défini.",
+      pickSaveError: "Impossible de définir l'emplacement de sauvegarde.",
       roomStatus: {
         senderEmptyMsg: "La salle est vide",
         receiverEmptyMsg:
@@ -313,6 +313,9 @@ export const fr: Messages = {
       zipError: "Erreur lors de la création du fichier ZIP.",
       fileNotFoundMsg:
         "Fichier '{fileName}' introuvable pour le téléchargement.",
+      confirmLeaveWhileTransferring:
+        "Des fichiers sont actuellement en cours de transfert. Quitter interrompra le transfert. Êtes-vous sûr?",
+      leaveWhileTransferringSuccess: "Salle quittée, transfert interrompu",
       html: {
         senderTab: "Envoyer",
         retrieveTab: "Récupérer",
@@ -323,7 +326,8 @@ export const fr: Messages = {
         Copy_dis: "Copier",
         inputRoomIdprompt: "Votre ID de salle (modifiable) :",
         joinRoomBtn: "Rejoindre la salle",
-        generateRoomId_tips: "ID Aléatoire",
+        generateSimpleId_tips: "ID Simple",
+        generateRandomId_tips: "ID Aléatoire",
         readClipboardToRoomId: "Coller l'ID de salle",
         enterRoomID_placeholder: "entrez l'ID de salle",
         retrieveMethod: "Méthode de récupération",

frontend/constants/messages/ja.ts

@@ -229,9 +229,11 @@ export const ja: Messages = {
       CurrentFileTransferring_tips: "ファイルが転送中です",
       OtherFileTransferring_tips: "現在の転送が完了するまでお待ちください",
       download_tips: "クリックしてファイルをダウンロード",
+      PendingSave_tips: "クリックしてファイルをローカルに保存", // 新增
       Saved_dis: "保存済み",
       Waiting_dis: "待機中",
       Download_dis: "ダウンロード",
+      Save_dis: "保存", // 新增
     },
     FileListDisplay: {
       sending_dis: "送信中",
@@ -247,9 +249,6 @@ export const ja: Messages = {
       chooseSavePath_tips:
         "大きなファイルやフォルダを選択したディレクトリに直接保存します。👉",
       chooseSavePath_dis: "保存場所を選択",
-      safeSave_dis: "安全保存",
-      safeSave_tooltip: "接続の中断を恐れる必要はありません。ここをクリックして、次回の再開のためにファイルを安全に保存してください",
-      safeSaveSuccessMsg: "ファイルが安全にディスクに保存されました。ページを安全に閉じることができ、転送の再開をサポートします！",
     },
     RetrieveMethod: {
       P: "おめでとう 🎉 共有コンテンツが取得待ちです：",
@@ -283,6 +282,9 @@ export const ja: Messages = {
         failMsg: "ルームへの参加に失敗しました：",
       },
       pickSaveMsg: "ディスクに直接保存しますか？",
+      pickSaveUnsupported: "ディレクトリピッカーはサポートされていません。",
+      pickSaveSuccess: "保存場所が設定されました。",
+      pickSaveError: "保存場所を設定できませんでした。",
       roomStatus: {
         senderEmptyMsg: "ルームは空です",
         receiverEmptyMsg: "招待を受けてルームに参加できます",
@@ -297,6 +299,8 @@ export const ja: Messages = {
       noFilesForFolderMsg: "フォルダ '{folderName}' にファイルが見つかりません。",
       zipError: "ZIP の作成中にエラーが発生しました。",
       fileNotFoundMsg: "ダウンロードするファイル '{fileName}' が見つかりません。",
+      confirmLeaveWhileTransferring: "現在ファイルが転送中です。退出すると転送が中断されます。よろしいですか？",
+      leaveWhileTransferringSuccess: "ルームを退出しました。転送が中断されました",
       html: {
         senderTab: "送信",
         retrieveTab: "取得",
@@ -307,7 +311,8 @@ export const ja: Messages = {
         Copy_dis: "コピー",
         inputRoomIdprompt: "ルームID（編集可能）：",
         joinRoomBtn: "ルームに参加",
-        generateRoomId_tips: "ランダムID",
+        generateSimpleId_tips: "シンプルID",
+        generateRandomId_tips: "ランダムID",
         readClipboardToRoomId: "ルームIDを貼り付け",
         enterRoomID_placeholder: "ルームIDを入力",
         retrieveMethod: "取得方法",

frontend/constants/messages/ko.ts

@@ -227,9 +227,11 @@ export const ko: Messages = {
       CurrentFileTransferring_tips: "파일 전송 중",
       OtherFileTransferring_tips: "현재 전송이 완료될 때까지 기다려주세요",
       download_tips: "파일을 다운로드하려면 클릭하세요",
+      PendingSave_tips: "로컬에 파일을 저장하려면 클릭하세요", // 新增
       Saved_dis: "저장됨",
       Waiting_dis: "대기 중",
       Download_dis: "다운로드",
+      Save_dis: "저장", // 新增
     },
     FileListDisplay: {
       sending_dis: "전송 중",
@@ -245,9 +247,6 @@ export const ko: Messages = {
       chooseSavePath_tips:
         "큰 파일이나 폴더를 선택한 디렉터리에 직접 저장합니다. 👉",
       chooseSavePath_dis: "저장 위치 선택",
-      safeSave_dis: "안전 저장",
-      safeSave_tooltip: "연결 중단을 두려워하지 마세요. 다음 재개를 위해 파일을 안전하게 저장하려면 여기를 클릭하세요",
-      safeSaveSuccessMsg: "파일이 디스크에 안전하게 저장되었습니다. 페이지를 안전하게 닫을 수 있으며 전송 재개를 지원합니다!",
     },
     RetrieveMethod: {
       P: "축하합니다 🎉 공유된 콘텐츠가 검색을 기다리고 있습니다:",
@@ -281,6 +280,9 @@ export const ko: Messages = {
         failMsg: "방 참여 실패:",
       },
       pickSaveMsg: "직접 디스크에 저장하시겠습니까?",
+      pickSaveUnsupported: "디렉토리 선택기가 지원되지 않습니다.",
+      pickSaveSuccess: "저장 위치가 설정되었습니다.",
+      pickSaveError: "저장 위치를 설정할 수 없습니다.",
       roomStatus: {
         senderEmptyMsg: "방이 비어 있습니다",
         receiverEmptyMsg: "초대를 수락하여 방에 참여할 수 있습니다",
@@ -295,6 +297,8 @@ export const ko: Messages = {
       noFilesForFolderMsg: "폴더 '{folderName}'에서 파일을 찾을 수 없습니다.",
       zipError: "ZIP 파일 생성 중 오류가 발생했습니다.",
       fileNotFoundMsg: "다운로드할 파일 '{fileName}'을(를) 찾을 수 없습니다.",
+      confirmLeaveWhileTransferring: "현재 파일이 전송 중입니다. 나가면 전송이 중단됩니다. 확실합니까?",
+      leaveWhileTransferringSuccess: "방을 나갔습니다. 전송이 중단되었습니다",
       html: {
         senderTab: "보내기",
         retrieveTab: "검색",
@@ -305,7 +309,8 @@ export const ko: Messages = {
         Copy_dis: "복사",
         inputRoomIdprompt: "방 ID (편집 가능):",
         joinRoomBtn: "방 참여",
-        generateRoomId_tips: "랜덤 ID",
+        generateSimpleId_tips: "간단 ID",
+        generateRandomId_tips: "랜덤 ID",
         readClipboardToRoomId: "방 ID 붙여넣기",
         enterRoomID_placeholder: "방 ID 입력",
         retrieveMethod: "검색 방법",

frontend/constants/messages/zh.ts

@@ -216,9 +216,11 @@ export const zh: Messages = {
       CurrentFileTransferring_tips: "文件正在传输中",
       OtherFileTransferring_tips: "请等待当前传输完成",
       download_tips: "点击下载文件",
+      PendingSave_tips: "点击保存文件到本地", // 新增
       Saved_dis: "已保存",
       Waiting_dis: "等待中",
       Download_dis: "下载",
+      Save_dis: "保存", // 新增
     },
     FileListDisplay: {
       sending_dis: "发送中",
@@ -233,10 +235,6 @@ export const zh: Messages = {
         "我们建议选择一个保存目录来直接将文件保存到磁盘。这样可以更方便地传输大文件和同步文件夹。",
       chooseSavePath_tips: "大文件或文件夹可直接保存到指定目录 👉",
       chooseSavePath_dis: "选择保存位置",
-      safeSave_dis: "安全保存",
-      safeSave_tooltip: "连接中断不要怕，点击这里安全保存文件，方便下次续传",
-      safeSaveSuccessMsg:
-        "文件已安全保存到磁盘，可以安全关闭页面，支持断点续传！",
     },
     RetrieveMethod: {
       P: "恭喜 🎉 共享内容等待接收：",
@@ -268,6 +266,9 @@ export const zh: Messages = {
         failMsg: "加入房间失败：",
       },
       pickSaveMsg: "直接保存到磁盘？",
+      pickSaveUnsupported: "不支持目录选择器。",
+      pickSaveSuccess: "保存位置已设置。",
+      pickSaveError: "无法设置保存位置。",
       roomStatus: {
         senderEmptyMsg: "房间为空",
         receiverEmptyMsg: "您可以接受邀请加入房间",
@@ -282,6 +283,8 @@ export const zh: Messages = {
       noFilesForFolderMsg: "在文件夹 '{folderName}' 中未找到文件。",
       zipError: "创建 ZIP 文件时出错。",
       fileNotFoundMsg: "未找到要下载的文件 '{fileName}'。",
+      confirmLeaveWhileTransferring: "当前有文件正在传输，退出将中断传输。确定要退出吗？",
+      leaveWhileTransferringSuccess: "已退出房间，传输已中断",
       html: {
         senderTab: "发送",
         retrieveTab: "接收",
@@ -292,7 +295,8 @@ export const zh: Messages = {
         Copy_dis: "复制",
         inputRoomIdprompt: "您的房间ID（可编辑）：",
         joinRoomBtn: "加入房间",
-        generateRoomId_tips: "随机ID",
+        generateSimpleId_tips: "简单ID",
+        generateRandomId_tips: "随机ID", 
         readClipboardToRoomId: "粘贴房间ID",
         enterRoomID_placeholder: "输入房间ID",
         retrieveMethod: "接收方式",

frontend/hooks/useFileTransferHandler.ts

@@ -1,9 +1,10 @@
-import { useCallback } from "react";
+import { useCallback, useEffect } from "react";
 import { CustomFile, FileMeta, fileMetadata } from "@/types/webrtc";
 import { Messages } from "@/types/messages";
 import JSZip from "jszip";
 import { downloadAs } from "@/lib/fileUtils";
 import { useFileTransferStore } from "@/stores/fileTransferStore";
+import { postLogToBackend } from "@/app/config/api";
 
 interface UseFileTransferHandlerProps {
   messages: Messages | null;
@@ -18,7 +19,7 @@ export function useFileTransferHandler({
   messages,
   putMessageInMs,
 }: UseFileTransferHandlerProps) {
-  // 从 store 中获取状态
+  // Get state from store
   const {
     shareContent,
     sendFiles,
@@ -26,7 +27,6 @@ export function useFileTransferHandler({
     retrievedFiles,
     retrievedFileMetas,
     setShareContent,
-    setSendFiles,
     addSendFiles,
     removeSendFile,
     setRetrievedContent,
@@ -68,7 +68,9 @@ export function useFileTransferHandler({
 
   const handleDownloadFile = useCallback(
     async (meta: FileMeta) => {
-      if (!messages) return;
+      if (!messages) {
+        return;
+      }
 
       if (meta.folderName && meta.folderName !== "") {
         const { retrievedFiles: latestRetrievedFiles } =
@@ -100,11 +102,11 @@ export function useFileTransferHandler({
         }
       } else {
         let retryCount = 0;
-        const maxRetries = 3; // 重试次数
+        const maxRetries = 3; // Retry count
 
         const findAndDownload = async (): Promise<boolean> => {
           retryCount++;
-          // 🔧 关键修复：使用最新的Store状态，而不是闭包中的旧状态
+          // 🔧 Key fix: Use the latest Store state instead of the old state in the closure
           const { retrievedFiles: latestRetrievedFiles } =
             useFileTransferStore.getState();
           const fileToDownload = latestRetrievedFiles.find(
@@ -112,27 +114,49 @@ export function useFileTransferHandler({
           );
 
           if (fileToDownload) {
+            // Check if file is empty
+            if (fileToDownload.size === 0) {
+              postLogToBackend(
+                `ERROR: File has 0 size! This explains the 0-byte download.`
+              );
+            }
+
+            // Check if file is a valid Blob
+            if (!(fileToDownload instanceof Blob)) {
+              postLogToBackend(
+                `WARNING: File is not a Blob object, type: ${typeof fileToDownload}`
+              );
+            }
+
             downloadAs(fileToDownload, fileToDownload.name);
             return true;
+          } else {
+            // Debug log: Record the case where file is not found
+            const availableFileNames = latestRetrievedFiles.map((f) => f.name);
+            postLogToBackend(
+              `File NOT found! Looking for: "${
+                meta.name
+              }", Available files: [${availableFileNames.join(", ")}]`
+            );
           }
 
           return false;
         };
 
-        // 首次尝试
+        // First attempt
         const found = await findAndDownload();
 
         if (!found) {
-          // 如果没找到，启动重试机制
+          // If not found, start retry mechanism
           const retryWithDelay = async (): Promise<void> => {
             while (retryCount < maxRetries) {
-              await new Promise((resolve) => setTimeout(resolve, 50)); // 固定50ms延迟，因为现在状态应该很快同步
+              await new Promise((resolve) => setTimeout(resolve, 50)); // Fixed 50ms delay, as the state should sync quickly now
               const foundInRetry = await findAndDownload();
               if (foundInRetry) {
                 return;
               }
             }
-            // 所有重试都失败了
+            // All retries failed
             putMessageInMs(
               messages.text.ClipboardApp.fileNotFoundMsg ||
                 `File '${meta.name}' not found for download.`,
@@ -140,12 +164,12 @@ export function useFileTransferHandler({
             );
           };
 
-          // 异步执行重试，不阻塞主线程
+          // Execute retry asynchronously without blocking the main thread
           retryWithDelay().catch(console.error);
         }
       }
     },
-    [messages, putMessageInMs] // 🔧 移除retrievedFiles依赖，因为我们现在直接从Store获取最新状态
+    [messages, putMessageInMs] // 🔧 Remove retrievedFiles dependency as we now get the latest state directly from Store
   );
 
   // Reset function specifically for receiver state (for leave room functionality)

frontend/hooks/useRoomManager.ts

@@ -9,7 +9,7 @@ function format_peopleMsg(template: string, peerCount: number) {
   return template.replace("{peerCount}", peerCount.toString());
 }
 
-// 移除所有 WebRTC 相关的 props 依赖
+// Remove all WebRTC related props dependencies
 interface UseRoomManagerProps {
   messages: Messages | null;
   putMessageInMs: (
@@ -23,7 +23,7 @@ export function useRoomManager({
   messages,
   putMessageInMs,
 }: UseRoomManagerProps) {
-  // 从 store 获取状态
+  // Get state from store
   const {
     shareRoomId,
     initShareRoomId,
@@ -36,6 +36,7 @@ export function useRoomManager({
     senderDisconnected,
     isSenderInRoom,
     isReceiverInRoom,
+    isAnyFileTransferring,
     setShareRoomId,
     setInitShareRoomId,
     setShareLink,
@@ -45,13 +46,13 @@ export function useRoomManager({
     resetSenderApp,
   } = useFileTransferStore();
 
-  // 加入房间方法 - 直接使用 webrtcService
+  // Join room method - directly use webrtcService
   const joinRoom = useCallback(
     async (isSenderSide: boolean, roomId: string) => {
       if (!messages) return;
 
       try {
-        // 如果是发送方且房间ID不是初始ID，需要先创建房间
+        // If it's the sender side and the room ID is not the initial ID, need to create the room first
         if (
           isSenderSide &&
           activeTab === "send" &&
@@ -77,7 +78,7 @@ export function useRoomManager({
           }
         }
 
-        // 确定实际要加入的房间ID
+        // Determine the actual room ID to join
         const actualRoomId =
           isSenderSide && roomId !== initShareRoomId
             ? roomId
@@ -85,7 +86,7 @@ export function useRoomManager({
             ? shareRoomId
             : roomId;
 
-        // 直接调用 service 方法，无需依赖注入
+        // Directly call the service method without dependency injection
         await webrtcService.joinRoom(actualRoomId, isSenderSide);
 
         putMessageInMs(
@@ -94,7 +95,7 @@ export function useRoomManager({
           6000
         );
 
-        // 更新分享链接
+        // Update share link
         if (isSenderSide) {
           const link = `${window.location.origin}${window.location.pathname}?roomId=${actualRoomId}`;
           setShareLink(link);
@@ -103,7 +104,7 @@ export function useRoomManager({
           }
         }
       } catch (error) {
-        console.error("[RoomManager] 加入房间失败:", error);
+        console.error("[RoomManager] Failed to join room:", error);
         let errorMsg = messages.text.ClipboardApp.joinRoom.failMsg;
         if (error instanceof Error) {
           errorMsg =
@@ -125,7 +126,7 @@ export function useRoomManager({
     ]
   );
 
-  // 生成分享链接并广播
+  // Generate share link and broadcast
   const generateShareLinkAndBroadcast = useCallback(async () => {
     if (!messages || !shareRoomId) return;
 
@@ -133,25 +134,31 @@ export function useRoomManager({
       if (sharePeerCount === 0) {
         putMessageInMs(messages.text.ClipboardApp.waitting_tips, true);
       } else {
-        // 直接调用 service 的广播方法
+        // Directly call the service's broadcast method
         await webrtcService.broadcastDataToAllPeers();
       }
 
-      // 更新分享链接
+      // Update share link
       const link = `${window.location.origin}${window.location.pathname}?roomId=${shareRoomId}`;
       setShareLink(link);
     } catch (error) {
-      console.error("[RoomManager] 生成分享链接失败:", error);
-      putMessageInMs("生成分享链接失败", true);
+      console.error("[RoomManager] Failed to generate share link:", error);
+      putMessageInMs("Failed to generate share link", true);
     }
   }, [messages, putMessageInMs, shareRoomId, sharePeerCount, setShareLink]);
 
-  // 接收方离开房间
+  // Receiver leave room
   const handleLeaveReceiverRoom = useCallback(async () => {
     if (!messages) return;
 
+    // Check if files are transferring and show confirmation
+    if (isAnyFileTransferring) {
+      const confirmed = window.confirm(messages.text.ClipboardApp.confirmLeaveWhileTransferring);
+      if (!confirmed) return;
+    }
+
     try {
-      // 调用后端 API 离开房间
+      // Call backend API to leave room
       if (webrtcService.receiver.roomId && webrtcService.receiver.peerId) {
         await leaveRoom(
           webrtcService.receiver.roomId,
@@ -159,44 +166,53 @@ export function useRoomManager({
         );
       }
 
-      putMessageInMs(messages.text.ClipboardApp.roomStatus.leftRoomMsg, false);
+      const message = isAnyFileTransferring 
+        ? messages.text.ClipboardApp.leaveWhileTransferringSuccess
+        : messages.text.ClipboardApp.roomStatus.leftRoomMsg;
+      putMessageInMs(message, false);
 
-      // 重置接收方状态
+      // Reset receiver state (clears all as per requirement)
       resetReceiverState();
 
-      // 清理 WebRTC 连接
+      // Clean up WebRTC connection
       await webrtcService.leaveRoom(false);
     } catch (error) {
-      console.error("[RoomManager] 接收方离开房间失败:", error);
-      putMessageInMs("离开房间失败", true);
+      console.error("[RoomManager] Receiver failed to leave room:", error);
+      putMessageInMs("Failed to leave room", true);
     }
-  }, [messages, putMessageInMs, resetReceiverState]);
+  }, [messages, putMessageInMs, resetReceiverState, isAnyFileTransferring]);
 
-  // 发送方重置应用状态
+  // Sender reset app state
   const resetSenderAppState = useCallback(async () => {
     try {
-      // 1. 清理 WebRTC 连接
+      // 1. Clean up WebRTC connection
       await webrtcService.leaveRoom(true);
 
-      // 2. 清除分享链接和进度
+      // 2. Clear share link and progress
       resetSenderApp();
 
-      // 3. 从后端获取新的房间ID
+      // 3. Fetch new room ID from backend
       const newRoomId = await fetchRoom();
       setShareRoomId(newRoomId || "");
       setInitShareRoomId(newRoomId || "");
     } catch (error) {
-      console.error("[RoomManager] 重置发送方状态失败:", error);
-      putMessageInMs("重置发送方状态失败", true);
+      console.error("[RoomManager] Failed to reset sender state:", error);
+      putMessageInMs("Failed to reset sender state", true);
     }
   }, [putMessageInMs, resetSenderApp, setShareRoomId, setInitShareRoomId]);
 
-  // 发送方离开房间
+  // Sender leave room
   const handleLeaveSenderRoom = useCallback(async () => {
     if (!messages) return;
 
+    // Check if files are transferring and show confirmation
+    if (isAnyFileTransferring) {
+      const confirmed = window.confirm(messages.text.ClipboardApp.confirmLeaveWhileTransferring);
+      if (!confirmed) return;
+    }
+
     try {
-      // 调用后端 API 离开房间
+      // Call backend API to leave room
       if (webrtcService.sender.roomId && webrtcService.sender.peerId) {
         await leaveRoom(
           webrtcService.sender.roomId,
@@ -204,18 +220,21 @@ export function useRoomManager({
         );
       }
 
-      putMessageInMs(messages.text.ClipboardApp.roomStatus.leftRoomMsg, true);
+      const message = isAnyFileTransferring 
+        ? messages.text.ClipboardApp.leaveWhileTransferringSuccess
+        : messages.text.ClipboardApp.roomStatus.leftRoomMsg;
+      putMessageInMs(message, true);
 
-      // 重置发送方状态并获取新房间ID
+      // Reset sender state and get new room ID (keeps files as per requirement)
       await resetSenderAppState();
     } catch (error) {
-      console.error("[RoomManager] 发送方离开房间失败:", error);
-      putMessageInMs("离开房间失败", true);
+      console.error("[RoomManager] Sender failed to leave room:", error);
+      putMessageInMs("Failed to leave room", true);
     }
-  }, [messages, putMessageInMs, resetSenderAppState]);
+  }, [messages, putMessageInMs, resetSenderAppState, isAnyFileTransferring]);
 
-  // 房间ID输入处理
-  const processRoomIdInput = useCallback(
+  // Room ID input processing
+    const processRoomIdInput = useCallback(
     debounce(async (input: string) => {
       if (!input.trim() || !messages) return;
 
@@ -234,14 +253,14 @@ export function useRoomManager({
           );
         }
       } catch (error) {
-        console.error("[RoomManager] 验证房间失败:", error);
-        putMessageInMs("验证房间失败", true);
+        console.error("[RoomManager] Failed to validate room:", error);
+        putMessageInMs("Failed to validate room", true);
       }
     }, 750),
     [messages, putMessageInMs, setShareRoomId]
   );
 
-  // 初始化发送方房间ID
+  // Initialize sender room ID
   useEffect(() => {
     if (
       messages &&
@@ -255,9 +274,10 @@ export function useRoomManager({
           setShareRoomId(newRoomId || "");
           setInitShareRoomId(newRoomId || "");
         } catch (err) {
-          console.error("[RoomManager] 获取初始房间失败:", err);
+          console.error("[RoomManager] Failed to fetch initial room:", err);
           const errorMsg =
-            messages.text?.ClipboardApp?.fetchRoom_err || "获取房间ID失败";
+            messages.text?.ClipboardApp?.fetchRoom_err ||
+            "Failed to fetch room ID";
           putMessageInMs(errorMsg, true);
         }
       };
@@ -272,7 +292,7 @@ export function useRoomManager({
     setInitShareRoomId,
   ]);
 
-  // 房间状态文本更新
+  // Room status text update
   useEffect(() => {
     if (!messages) {
       if (activeTab === "send") setShareRoomStatusText("");
@@ -317,7 +337,7 @@ export function useRoomManager({
   ]);
 
   return {
-    // 状态
+    // State
     shareRoomId,
     initShareRoomId,
     shareLink,
@@ -329,7 +349,7 @@ export function useRoomManager({
     isSenderInRoom,
     isReceiverInRoom,
 
-    // 方法
+    // Methods
     processRoomIdInput,
     joinRoom,
     generateShareLinkAndBroadcast,

frontend/hooks/useWebRTCConnection.ts

@@ -3,7 +3,7 @@ import { webrtcService } from "@/lib/webrtcService";
 import { useFileTransferStore } from "@/stores/fileTransferStore";
 import type { Messages } from "@/types/messages";
 
-// 保留类型定义以保持兼容性
+// Retain type definitions for compatibility
 export type PeerProgressDetails = { progress: number; speed: number };
 export type FileProgressPeers = { [peerId: string]: PeerProgressDetails };
 export type ProgressState = { [fileId: string]: FileProgressPeers };
@@ -18,10 +18,9 @@ interface UseWebRTCConnectionProps {
 }
 
 export function useWebRTCConnection({
-  messages,
-  putMessageInMs,
+  // Retaining interface compatibility but these are no longer used
 }: UseWebRTCConnectionProps) {
-  // 从 store 获取状态
+  // Get state from store
   const {
     sharePeerCount,
     retrievePeerCount,
@@ -31,7 +30,7 @@ export function useWebRTCConnection({
     setIsAnyFileTransferring,
   } = useFileTransferStore();
 
-  // 计算是否有文件正在传输
+  // Calculate if any file is being transferred
   const isAnyFileTransferring = useMemo(() => {
     const allProgress = [
       ...Object.values(sendProgress),
@@ -49,14 +48,14 @@ export function useWebRTCConnection({
   }, [isAnyFileTransferring, setIsAnyFileTransferring]);
 
   return {
-    // 状态从 store 获取
+    // State obtained from store
     sharePeerCount,
     retrievePeerCount,
     senderDisconnected,
     sendProgress,
     receiveProgress,
 
-    // 方法直接从 service 暴露
+    // Methods exposed directly from service
     broadcastDataToAllPeers:
       webrtcService.broadcastDataToAllPeers.bind(webrtcService),
     requestFile: webrtcService.requestFile.bind(webrtcService),
@@ -64,13 +63,12 @@ export function useWebRTCConnection({
     setReceiverDirectoryHandle:
       webrtcService.setReceiverDirectoryHandle.bind(webrtcService),
     getReceiverSaveType: webrtcService.getReceiverSaveType.bind(webrtcService),
-    manualSafeSave: webrtcService.manualSafeSave.bind(webrtcService),
 
-    // 重置连接方法
+    // Reset connection methods
     resetSenderConnection: () => webrtcService.leaveRoom(true),
     resetReceiverConnection: () => webrtcService.leaveRoom(false),
 
-    // 为了兼容性，保留这些属性（但实际上不再需要）
+    // For compatibility, retain these properties (but they are no longer needed)
     sender: webrtcService.sender,
     receiver: webrtcService.receiver,
   };

frontend/lib/browserUtils.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser detection utility functions
+ * Extended to support Firefox WebRTC compatibility handling
+ */
+
+/**
+ * Detect if the browser is Chrome
+ * @returns {boolean} Returns true if it's Chrome, otherwise false
+ */
+export const isChrome = (): boolean => {
+  // Detect Chrome browser, excluding Chromium-based Edge
+  const userAgent = navigator.userAgent;
+
+  return (
+    userAgent.includes("Chrome") && !userAgent.includes("Edg") // Exclude Edge
+  );
+};
+
+/**
+ * Detect if programmatic download is supported
+ * Chrome supports automatic download after long transfers, other browsers may have limitations
+ * @returns {boolean} Returns true if automatic download is supported
+ */
+
+export const supportsAutoDownload = (): boolean => {
+  return isChrome();
+};

frontend/lib/fileReceiver.ts

@@ -1,83 +1,138 @@
-// Flow for receiving file(s)/folder(s): First, receive file metadata in batch, [decide if the user needs to select a save directory],
-// then click to request, receive the file content, and after receiving endMeta, send an ack to finish.
-// Flow for receiving a folder (same as above): Receive a batch file request.
-import { SpeedCalculator } from "@/lib/speedCalculator";
+// 🚀 Modernized FileReceiver using modular architecture
+// This file now serves as a compatibility layer for the new modular receive system
+
 import WebRTC_Recipient from "./webrtc_Recipient";
-import {
-  CustomFile,
-  fileMetadata,
-  WebRTCMessage,
-  FolderProgress,
-  CurrentString,
-  StringMetadata,
-  StringChunk,
-  FileEnd,
-  FileHandlers,
-  FileMeta,
-  FileRequest,
-  FolderComplete,
-} from "@/types/webrtc";
+import { CustomFile, fileMetadata } from "@/types/webrtc";
+import { createFileReceiveService, FileReceiveOrchestrator } from "./receive";
 
 /**
- * Manages the state of an active file reception.
+ * 🚀 FileReceiver - Compatibility wrapper for the new modular architecture
+ *
+ * This class maintains backward compatibility while using the new modular receive system.
+ * All heavy lifting is now done by the FileReceiveOrchestrator and its specialized modules.
  */
-interface ActiveFileReception {
-  meta: fileMetadata; // If meta is present, it means this file is currently being received; null means no file is being received.
-  chunks: (ArrayBuffer | null)[]; // Received file chunks (stored in memory).
-  receivedSize: number;
-  initialOffset: number; // For resuming downloads
-  fileHandle: FileSystemFileHandle | null; // Object related to writing to disk -- current file.
-  writeStream: FileSystemWritableFileStream | null; // Object related to writing to disk.
-  completionNotifier: {
-    resolve: () => void;
-    reject: (reason?: any) => void;
-  };
-}
-
 class FileReceiver {
-  // region Private Properties
-  private readonly webrtcConnection: WebRTC_Recipient;
-  private readonly largeFileThreshold: number = 1 * 1024 * 1024 * 1024; // 1 GB, larger files will prompt the user to select a directory for direct disk saving.
-  private readonly speedCalculator: SpeedCalculator;
-  private fileHandlers: FileHandlers;
+  private orchestrator: FileReceiveOrchestrator;
 
-  private peerId: string = "";
-  private saveDirectory: FileSystemDirectoryHandle | null = null;
+  // Public properties for backward compatibility
+  public saveType: Record<string, boolean> = {};
 
-  // State Management
-  private pendingFilesMeta = new Map<string, fileMetadata>(); // Stores file metadata, fileId: meta
-  private folderProgresses: Record<string, FolderProgress> = {}; // Folder progress information, fileId: {totalSize: 0, receivedSize: 0, fileIds: []};
-  public saveType: Record<string, boolean> = {}; // fileId or folderName -> isSavedToDisk
+  // Callbacks - these are forwarded to the orchestrator
+  public onFileMetaReceived: ((meta: fileMetadata) => void) | undefined =
+    undefined;
+  public onStringReceived: ((str: string) => void) | undefined = undefined;
+  public onFileReceived: ((file: CustomFile) => Promise<void>) | undefined =
+    undefined;
 
-  // Active transfer state
-  private activeFileReception: ActiveFileReception | null = null;
-  private activeStringReception: CurrentString | null = null;
-  private currentFolderName: string | null = null; // The name of the folder currently being received, or null if not receiving a folder.
+  constructor(webrtcRecipient: WebRTC_Recipient) {
+    // Create the orchestrator using the factory function
+    this.orchestrator = createFileReceiveService(webrtcRecipient);
 
-  // Callbacks
-  public onFileMetaReceived: ((meta: fileMetadata) => void) | null = null;
-  public onStringReceived: ((str: string) => void) | null = null;
-  public onFileReceived: ((file: CustomFile) => Promise<void>) | null = null;
-  private progressCallback:
-    | ((id: string, progress: number, speed: number) => void)
-    | null = null;
-  // endregion
+    // Set up callback forwarding
+    this.setupCallbackForwarding();
 
-  constructor(WebRTC_recipient: WebRTC_Recipient) {
-    this.webrtcConnection = WebRTC_recipient;
-    this.speedCalculator = new SpeedCalculator();
-
-    this.fileHandlers = {
-      string: this.handleReceivedStringChunk.bind(this),
-      stringMetadata: this.handleStringMetadata.bind(this),
-      fileMeta: this.handleFileMetadata.bind(this),
-      fileEnd: this.handleFileEnd.bind(this),
-    };
-
-    this.setupDataHandler();
+    this.log("log", "FileReceiver initialized with modular architecture");
   }
 
-  // region Logging and Error Handling
+  /**
+   * Set up callback forwarding to the orchestrator
+   */
+  private setupCallbackForwarding(): void {
+    // Forward file metadata callback
+    this.orchestrator.onFileMetaReceived = (meta: fileMetadata) => {
+      // Update saveType for backward compatibility
+      this.saveType = this.orchestrator.getSaveType();
+
+      if (this.onFileMetaReceived) {
+        this.onFileMetaReceived(meta);
+      }
+    };
+
+    // Forward string received callback
+    this.orchestrator.onStringReceived = (str: string) => {
+      if (this.onStringReceived) {
+        this.onStringReceived(str);
+      }
+    };
+
+    // Forward file received callback
+    this.orchestrator.onFileReceived = async (file: CustomFile) => {
+      if (this.onFileReceived) {
+        await this.onFileReceived(file);
+      }
+    };
+  }
+
+  /**
+   * Set progress callback
+   */
+  public setProgressCallback(
+    callback: (fileId: string, progress: number, speed: number) => void
+  ): void {
+    this.orchestrator.setProgressCallback(callback);
+  }
+
+  /**
+   * Set save directory
+   */
+  public setSaveDirectory(directory: FileSystemDirectoryHandle): Promise<void> {
+    return this.orchestrator.setSaveDirectory(directory);
+  }
+
+  /**
+   * Request a single file from the peer
+   */
+  public async requestFile(fileId: string, singleFile = true): Promise<void> {
+    return this.orchestrator.requestFile(fileId, singleFile);
+  }
+
+  /**
+   * Request all files belonging to a folder from the peer
+   */
+  public async requestFolder(folderName: string): Promise<void> {
+    return this.orchestrator.requestFolder(folderName);
+  }
+
+  /**
+   * Graceful shutdown
+   */
+  public gracefulShutdown(reason: string = "CONNECTION_LOST"): void {
+    this.orchestrator.gracefulShutdown(reason);
+
+    // Update saveType for backward compatibility
+    this.saveType = {};
+  }
+
+  /**
+   * Force reset all internal states
+   */
+  public forceReset(): void {
+    this.orchestrator.forceReset();
+
+    // Update saveType for backward compatibility
+    this.saveType = {};
+  }
+
+  /**
+   * Get transfer statistics (for debugging and monitoring)
+   */
+  public getTransferStats() {
+    return this.orchestrator.getTransferStats();
+  }
+
+  /**
+   * Clean up all resources
+   */
+  public cleanup(): void {
+    this.orchestrator.cleanup();
+    this.saveType = {};
+  }
+
+  // ===== Private Methods =====
+
+  /**
+   * Logging utility
+   */
   private log(
     level: "log" | "warn" | "error",
     message: string,
@@ -87,512 +142,36 @@ class FileReceiver {
     console[level](prefix, message, context || "");
   }
 
-  private fireError(message: string, context?: Record<string, any>) {
-    if (this.webrtcConnection.fireError) {
-      // @ts-ignore
-      this.webrtcConnection.fireError(message, {
-        ...context,
-        component: "FileReceiver",
-      });
-    } else {
-      this.log("error", message, context);
-    }
+  // ===== Backward Compatibility Getters =====
 
-    if (this.activeFileReception) {
-      this.activeFileReception.completionNotifier.reject(new Error(message));
-      this.activeFileReception = null;
-    }
-  }
-  // endregion
-
-  // region Setup and Public API
-  private setupDataHandler(): void {
-    this.webrtcConnection.onDataReceived = this.handleReceivedData.bind(this);
-  }
-
-  public setProgressCallback(
-    callback: (fileId: string, progress: number, speed: number) => void
-  ): void {
-    this.progressCallback = callback;
-  }
-
-  public setSaveDirectory(directory: FileSystemDirectoryHandle): Promise<void> {
-    this.saveDirectory = directory;
-    return Promise.resolve();
+  /**
+   * Get pending files metadata (for backward compatibility)
+   */
+  public getPendingFilesMeta(): Map<string, fileMetadata> {
+    return this.orchestrator.getPendingFilesMeta();
   }
 
   /**
-   * Requests a single file from the peer.
+   * Get folder progresses (for backward compatibility)
    */
-  public async requestFile(fileId: string, singleFile = true): Promise<void> {
-    if (this.activeFileReception) {
-      this.log("warn", "Another file reception is already in progress.");
-      return;
-    }
-
-    if (singleFile) this.currentFolderName = null;
-
-    const fileInfo = this.pendingFilesMeta.get(fileId);
-    if (!fileInfo) {
-      this.fireError("File info not found for the requested fileId", {
-        fileId,
-      });
-      return;
-    }
-
-    const shouldSaveToDisk =
-      !!this.saveDirectory || fileInfo.size >= this.largeFileThreshold;
-
-    // Set saveType at the beginning of the request to prevent race conditions in the UI
-    this.saveType[fileInfo.fileId] = shouldSaveToDisk;
-    if (this.currentFolderName) {
-      this.saveType[this.currentFolderName] = shouldSaveToDisk;
-    }
-
-    let offset = 0;
-    if (shouldSaveToDisk && this.saveDirectory) {
-      try {
-        const folderHandle = await this.createFolderStructure(
-          fileInfo.fullName
-        );
-        const fileHandle = await folderHandle.getFileHandle(fileInfo.name, {
-          create: false,
-        });
-        const file = await fileHandle.getFile();
-        offset = file.size;
-
-        if (offset === fileInfo.size) {
-          this.log("log", "File already fully downloaded.", { fileId });
-          // Optionally, trigger a "completed" state in the UI directly
-          this.progressCallback?.(fileId, 1, 0);
-          return; // Skip the request
-        }
-        this.log("log", `Resuming file from offset: ${offset}`, { fileId });
-      } catch (e) {
-        // File does not exist, starting from scratch
-        this.log("log", "Partial file not found, starting from scratch.", {
-          fileId,
-        });
-        offset = 0;
-      }
-    }
-
-    const receptionPromise = new Promise<void>((resolve, reject) => {
-      this.activeFileReception = {
-        meta: fileInfo,
-        chunks: [],
-        receivedSize: 0,
-        initialOffset: offset,
-        fileHandle: null,
-        writeStream: null,
-        completionNotifier: { resolve, reject },
-      };
-    });
-
-    if (shouldSaveToDisk) {
-      await this.createDiskWriteStream(fileInfo, offset);
-    }
-
-    const request: FileRequest = { type: "fileRequest", fileId, offset };
-    if (this.peerId) {
-      this.webrtcConnection.sendData(JSON.stringify(request), this.peerId);
-      this.log("log", "Sent fileRequest", { request });
-    }
-
-    return receptionPromise;
+  public getFolderProgresses(): Record<string, any> {
+    return this.orchestrator.getFolderProgresses();
   }
 
   /**
-   * Requests all files belonging to a folder from the peer.
+   * Check if there's an active file reception
    */
-  public async requestFolder(folderName: string): Promise<void> {
-    const folderProgress = this.folderProgresses[folderName];
-    if (!folderProgress || folderProgress.fileIds.length === 0) {
-      this.log("warn", "No files found for the requested folder.", {
-        folderName,
-      });
-      return;
-    }
-
-    // Pre-calculate total size of already downloaded parts of the folder
-    let initialFolderReceivedSize = 0;
-    if (this.saveDirectory) {
-      for (const fileId of folderProgress.fileIds) {
-        const fileInfo = this.pendingFilesMeta.get(fileId);
-        if (fileInfo) {
-          try {
-            const folderHandle = await this.createFolderStructure(
-              fileInfo.fullName
-            );
-            const fileHandle = await folderHandle.getFileHandle(fileInfo.name, {
-              create: false,
-            });
-            const file = await fileHandle.getFile();
-            initialFolderReceivedSize += file.size;
-          } catch (e) {
-            // File doesn't exist, so its size is 0.
-          }
-        }
-      }
-    }
-    folderProgress.receivedSize = initialFolderReceivedSize;
-    this.log(
-      "log",
-      `Requesting to receive folder, initial received size: ${initialFolderReceivedSize}`,
-      { folderName }
-    );
-
-    this.currentFolderName = folderName;
-    for (const fileId of folderProgress.fileIds) {
-      try {
-        await this.requestFile(fileId, false);
-      } catch (error) {
-        this.fireError(
-          `Failed to receive file ${fileId} in folder ${folderName}`,
-          { error }
-        );
-        // Stop receiving other files in the folder on error
-        break;
-      }
-    }
-    this.currentFolderName = null;
-
-    // After the loop, the receiver has requested all necessary files.
-    // Send a completion message to the sender to sync the final state.
-    const folderComplete: FolderComplete = {
-      type: "FolderComplete",
-      folderName: folderName,
-    };
-
-    if (this.peerId) {
-      this.webrtcConnection.sendData(
-        JSON.stringify(folderComplete),
-        this.peerId
-      );
-      this.log(
-        "log",
-        `Sent folderComplete message for ${folderName} to peer ${this.peerId}`
-      );
-    }
-  }
-  // endregion
-
-  // region WebRTC Data Handlers
-  private async handleReceivedData(
-    data: string | ArrayBuffer,
-    peerId: string
-  ): Promise<void> {
-    this.peerId = peerId;
-
-    if (typeof data === "string") {
-      try {
-        const parsedData = JSON.parse(data) as WebRTCMessage;
-
-        const handler =
-          this.fileHandlers[parsedData.type as keyof FileHandlers];
-        if (handler) {
-          await handler(parsedData, peerId);
-        } else {
-          console.warn(
-            `[DEBUG] ⚠️ FileReceiver 未找到处理器: ${parsedData.type}`
-          );
-        }
-      } catch (error) {
-        this.fireError("Error parsing received JSON data", { error });
-      }
-    } else if (data instanceof ArrayBuffer) {
-      if (!this.activeFileReception) {
-        this.fireError(
-          "Received a file chunk without an active file reception.",
-          { peerId }
-        );
-        return;
-      }
-      this.updateProgress(data.byteLength);
-      await this.handleFileChunk(data);
-    }
+  public hasActiveFileReception(): boolean {
+    const stats = this.orchestrator.getTransferStats();
+    return stats.stateManager.hasActiveFileReception;
   }
 
-  private handleFileMetadata(metadata: fileMetadata): void {
-    if (this.pendingFilesMeta.has(metadata.fileId)) {
-      console.log(
-        `[DEBUG] 📥 FileReceiver 文件元数据已存在，忽略: ${metadata.fileId}`
-      );
-      return; // Ignore if already received.
-    }
-
-    this.pendingFilesMeta.set(metadata.fileId, metadata);
-
-    if (this.onFileMetaReceived) {
-      this.onFileMetaReceived(metadata);
-    } else {
-      console.error(`[DEBUG] ❌ FileReceiver onFileMetaReceived 回调不存在!`);
-    }
-    // Record the file size for folder progress calculation.
-    if (metadata.folderName) {
-      const folderId = metadata.folderName;
-      if (!(folderId in this.folderProgresses)) {
-        this.folderProgresses[folderId] = {
-          totalSize: 0,
-          receivedSize: 0,
-          fileIds: [],
-        };
-      }
-      const folderProgress = this.folderProgresses[folderId];
-      if (!folderProgress.fileIds.includes(metadata.fileId)) {
-        // Prevent duplicate calculation
-        folderProgress.totalSize += metadata.size;
-        folderProgress.fileIds.push(metadata.fileId);
-      }
-    }
-  }
-
-  private handleStringMetadata(metadata: StringMetadata): void {
-    this.activeStringReception = {
-      length: metadata.length,
-      chunks: [],
-      receivedChunks: 0,
-    };
-  }
-
-  private handleReceivedStringChunk(data: StringChunk): void {
-    if (!this.activeStringReception) return;
-
-    this.activeStringReception.chunks[data.index] = data.chunk;
-    this.activeStringReception.receivedChunks++;
-
-    if (this.activeStringReception.receivedChunks === data.total) {
-      const fullString = this.activeStringReception.chunks.join("");
-      this.onStringReceived?.(fullString);
-      this.activeStringReception = null;
-    }
-  }
-
-  private async handleFileEnd(metadata: FileEnd): Promise<void> {
-    this.log("log", "File transmission ended", { metadata });
-    const reception = this.activeFileReception;
-    if (!reception || reception.meta.fileId !== metadata.fileId) {
-      this.log("warn", "Received fileEnd for unexpected file", { metadata });
-      return;
-    }
-
-    // 🔧 关键修复：先完成文件处理，确保文件添加到Store
-    await this.finalizeFileReceive();
-
-    // 🏗️ 架构重构：确保Store状态完全同步后再触发进度回调
-    if (!this.currentFolderName) {
-      // 🔧 优化的异步确保机制 - 确保Store状态完全同步
-      await Promise.resolve(); // 确保当前执行栈完成
-      await new Promise<void>((resolve) => {
-        // 使用更长的延迟确保Store状态完全更新
-        setTimeout(() => {
-          this.progressCallback?.(reception.meta.fileId, 1, 0);
-          resolve();
-        }, 10); // 增加到10ms确保Store状态完全同步
-      });
-    }
-
-    this.sendFileAck(reception.meta.fileId);
-    this.log("log", "Sent file-finish ack", { fileId: reception.meta.fileId });
-
-    reception.completionNotifier.resolve();
-    this.activeFileReception = null;
-  }
-  // endregion
-
-  // region File and Folder Processing
-  private async handleFileChunk(chunk: ArrayBuffer): Promise<void> {
-    if (!this.activeFileReception) return;
-
-    if (this.activeFileReception.writeStream) {
-      await this.writeLargeFileChunk(chunk);
-    } else {
-      this.activeFileReception.chunks.push(chunk);
-    }
-  }
-
-  private async finalizeFileReceive(): Promise<void> {
-    if (!this.activeFileReception) return;
-
-    if (this.activeFileReception.writeStream) {
-      await this.finalizeLargeFileReceive();
-    } else {
-      await this.finalizeMemoryFileReceive();
-    }
-  }
-
-  private updateProgress(byteLength: number): void {
-    if (!this.peerId || !this.activeFileReception) return;
-
-    this.activeFileReception.receivedSize += byteLength;
-    const reception = this.activeFileReception;
-    const totalReceived = reception.initialOffset + reception.receivedSize;
-
-    if (this.currentFolderName) {
-      const folderProgress = this.folderProgresses[this.currentFolderName];
-      if (!folderProgress) return;
-      // This is tricky: folder progress needs to sum up individual file progresses.
-      // For simplicity, we'll estimate based on total received for the active file.
-      // A more accurate implementation would track offsets for all files in the folder.
-      folderProgress.receivedSize += byteLength; // This is an approximation
-
-      this.speedCalculator.updateSendSpeed(
-        this.peerId,
-        folderProgress.receivedSize
-      );
-      const speed = this.speedCalculator.getSendSpeed(this.peerId);
-      const progress =
-        folderProgress.totalSize > 0
-          ? folderProgress.receivedSize / folderProgress.totalSize
-          : 0;
-      this.progressCallback?.(this.currentFolderName, progress, speed);
-    } else {
-      this.speedCalculator.updateSendSpeed(this.peerId, totalReceived);
-      const speed = this.speedCalculator.getSendSpeed(this.peerId);
-      const progress =
-        reception.meta.size > 0 ? totalReceived / reception.meta.size : 0;
-      this.progressCallback?.(reception.meta.fileId, progress, speed);
-    }
-  }
-  // endregion
-
-  // region Disk Operations
-  private async createDiskWriteStream(
-    meta: FileMeta,
-    offset: number
-  ): Promise<void> {
-    if (!this.saveDirectory || !this.activeFileReception) {
-      this.log("warn", "Save directory not set, falling back to in-memory.");
-      return;
-    }
-
-    try {
-      const folderHandle = await this.createFolderStructure(meta.fullName);
-      const fileHandle = await folderHandle.getFileHandle(meta.name, {
-        create: true,
-      });
-      // Use keepExistingData: true to append
-      const writeStream = await fileHandle.createWritable({
-        keepExistingData: true,
-      });
-      // Seek to the offset to start writing from there
-      await writeStream.seek(offset);
-
-      this.activeFileReception.fileHandle = fileHandle;
-      this.activeFileReception.writeStream = writeStream;
-    } catch (err) {
-      this.fireError("Failed to create file on disk", {
-        err,
-        fileName: meta.name,
-      });
-    }
-  }
-
-  private async createFolderStructure(
-    fullName: string
-  ): Promise<FileSystemDirectoryHandle> {
-    if (!this.saveDirectory) {
-      throw new Error("Save directory not set");
-    }
-
-    const parts = fullName.split("/");
-    parts.pop(); // Remove filename
-
-    let currentDir = this.saveDirectory;
-    for (const part of parts) {
-      if (part) {
-        currentDir = await currentDir.getDirectoryHandle(part, {
-          create: true,
-        });
-      }
-    }
-    return currentDir;
-  }
-
-  private async writeLargeFileChunk(chunk: ArrayBuffer): Promise<void> {
-    const stream = this.activeFileReception?.writeStream;
-    if (!stream) {
-      // Fallback to memory if stream is not available for some reason
-      this.activeFileReception?.chunks.push(chunk);
-      return;
-    }
-    try {
-      await stream.write(chunk);
-      this.activeFileReception?.chunks.push(null); // Keep track of chunk count
-    } catch (error) {
-      this.fireError("Error writing chunk to disk", { error });
-    }
-  }
-
-  private async finalizeLargeFileReceive(): Promise<void> {
-    const reception = this.activeFileReception;
-    if (!reception?.writeStream || !reception.fileHandle) return;
-
-    try {
-      await reception.writeStream.close();
-    } catch (error) {
-      this.fireError("Error closing write stream", { error });
-    }
-  }
-  // endregion
-
-  // region In-Memory Operations
-  private async finalizeMemoryFileReceive(): Promise<void> {
-    const reception = this.activeFileReception;
-    if (!reception) return;
-
-    const fileBlob = new Blob(reception.chunks as ArrayBuffer[], {
-      type: reception.meta.fileType,
-    });
-    const file = new File([fileBlob], reception.meta.name, {
-      type: reception.meta.fileType,
-    });
-
-    const customFile = Object.assign(file, {
-      fullName: reception.meta.fullName,
-      folderName: this.currentFolderName,
-    }) as CustomFile;
-
-    if (this.onFileReceived) {
-      // 🔧 关键修复：确保 onFileReceived 回调完全同步执行完成
-      await this.onFileReceived(customFile);
-      // 🔧 多重确认机制：确保 Store 状态完全同步
-      await Promise.resolve(); // 第一层确认
-      await new Promise<void>((resolve) => setTimeout(() => resolve(), 0)); // 第二层确认
-    }
-  }
-  // endregion
-
-  // region Communication
-  private sendFileAck(fileId: string): void {
-    if (!this.peerId) return;
-    const confirmation = JSON.stringify({ type: "fileAck", fileId });
-    this.webrtcConnection.sendData(confirmation, this.peerId);
-  }
-  // endregion
-
-  public gracefulShutdown(): void {
-    if (this.activeFileReception?.writeStream) {
-      this.log(
-        "log",
-        "Attempting to gracefully close write stream on page unload."
-      );
-      // We don't await this, as beforeunload does not wait for promises.
-      // This is a "best effort" attempt to flush the buffer to disk.
-      this.activeFileReception.writeStream.close().catch((err) => {
-        this.log("error", "Error closing stream during graceful shutdown", {
-          err,
-        });
-      });
-    }
-
-    // 🔧 清理所有内部状态，确保重新连接时能正确接收文件元数据
-    this.pendingFilesMeta.clear();
-    this.folderProgresses = {};
-    this.saveType = {};
-    this.activeFileReception = null;
-    this.activeStringReception = null;
-    this.currentFolderName = null;
+  /**
+   * Get current peer ID
+   */
+  public getCurrentPeerId(): string {
+    const stats = this.orchestrator.getTransferStats();
+    return stats.stateManager.currentPeerId;
   }
 }
 

frontend/lib/fileSender.ts

@@ -1,449 +1,53 @@
-// Flow for sending file(s)/folder(s): First, send file metadata, wait for the receiver's request, then send the file content.
-// After the file is sent, send an endMeta, wait for the receiver's ack, and finish.
-// Flow for sending a folder (same as above): Receive a batch file request.
-// Loop through and send the metadata for all files, then record the file size information for the folder part to calculate progress.
-// The receiving display end distinguishes between single files and folders.
-import { generateFileId } from "@/lib/fileUtils";
-import { SpeedCalculator } from "@/lib/speedCalculator";
+// 🚀 New process - Receiver-initiated file transfer
+// Refactored FileSender - Using modular architecture
+
 import WebRTC_Initiator from "./webrtc_Initiator";
-import {
-  CustomFile,
-  fileMetadata,
-  WebRTCMessage,
-  PeerState,
-  FolderMeta,
-  FileAck,
-  FileRequest,
-  FolderComplete,
-} from "@/types/webrtc";
+import { CustomFile } from "@/types/webrtc";
+import { FileTransferOrchestrator } from "./transfer/FileTransferOrchestrator";
 
+/**
+ * 🚀 FileSender - Backward compatible wrapper layer
+ *
+ * Refactoring notes:
+ * - Original 875-line monolithic class refactored into modular architecture
+ * - Internally uses FileTransferOrchestrator for unified orchestration
+ * - Maintains 100% backward compatible public API
+ * - Gains advantages such as high-performance file reading and intelligent backpressure control
+ */
 class FileSender {
-  private webrtcConnection: WebRTC_Initiator;
-  private peerStates: Map<string, PeerState>;
-  private readonly chunkSize: number;
-  private readonly maxBufferSize: number;
-  private pendingFiles: Map<string, CustomFile>;
-  private pendingFolerMeta: Record<string, FolderMeta>;
-  private speedCalculator: SpeedCalculator;
+  private orchestrator: FileTransferOrchestrator;
 
-  constructor(WebRTC_initiator: WebRTC_Initiator) {
-    this.webrtcConnection = WebRTC_initiator;
-
-    // Maintain independent sending states for each receiver
-    this.peerStates = new Map(); // Map<peerId, PeerState>
-
-    this.chunkSize = 65536; // 64 KB chunks
-    this.maxBufferSize = 10; // Number of chunks to pre-read
-    this.pendingFiles = new Map(); // All files pending to be sent (by reference) {fileId: CustomFile}
-
-    this.pendingFolerMeta = {}; // Metadata for folders (total size, total file count), used for tracking transfer progress
-
-    // Create a SpeedCalculator instance
-    this.speedCalculator = new SpeedCalculator();
-    this.setupDataHandler();
+  constructor(webrtcConnection: WebRTC_Initiator) {
+    this.orchestrator = new FileTransferOrchestrator(webrtcConnection);
+    console.log("[FileSender] ✅ Initialized with modular architecture");
   }
 
-  // region Logging and Error Handling
-  private log(
-    level: "log" | "warn" | "error",
-    message: string,
-    context?: Record<string, any>
-  ) {
-    const prefix = `[FileSender]`;
-    console[level](prefix, message, context || "");
+  public sendFileMeta(files: CustomFile[], peerId?: string): void {
+    return this.orchestrator.sendFileMeta(files, peerId);
   }
 
-  private fireError(message: string, context?: Record<string, any>) {
-    this.webrtcConnection.fireError(message, {
-      ...context,
-      component: "FileSender",
-    });
-  }
-  // endregion
-  // Initialize state for a new receiver
-  private getPeerState(peerId: string): PeerState {
-    if (!this.peerStates.has(peerId)) {
-      this.peerStates.set(peerId, {
-        isSending: false, // Used to determine if a file is successfully sent. True before sending, false after receiving ack.
-        bufferQueue: [], // Pre-read buffer to improve sending efficiency.
-        readOffset: 0, // Read position, used by the sending function.
-        isReading: false, // Whether reading is in progress, used by the sending function to avoid duplicate reads.
-
-        currentFolderName: "", // If the current file belongs to a folder, assign the folder name here.
-        totalBytesSent: {}, // Bytes sent for a file/folder, used for progress calculation; {fileId: 0}
-        progressCallback: null, // Progress callback.
-      });
-    }
-    return this.peerStates.get(peerId)!; // ! Non-Null Assertion Operator
-  }
-
-  private setupDataHandler(): void {
-    this.webrtcConnection.onDataReceived = (data, peerId) => {
-      if (typeof data === "string") {
-        try {
-          const parsedData = JSON.parse(data) as WebRTCMessage;
-          this.handleSignalingMessage(parsedData, peerId);
-        } catch (error) {
-          this.fireError("Error parsing received JSON data", { error, peerId });
-        }
-      }
-    };
-  }
-
-  private handleSignalingMessage(message: WebRTCMessage, peerId: string): void {
-    const peerState = this.getPeerState(peerId);
-    switch (message.type) {
-      case "fileRequest":
-        this.handleFileRequest(message as FileRequest, peerId);
-        break;
-      case "fileAck":
-        peerState.isSending = false;
-        this.log("log", `Received file-finish ack from peer ${peerId}`, {
-          fileId: (message as FileAck).fileId,
-        });
-        break;
-      case "folderComplete":
-        const folderName = (message as FolderComplete).folderName;
-        this.log(
-          "log",
-          `Received folderComplete message for ${folderName} from peer ${peerId}`
-        );
-        // The receiver has confirmed the folder is complete.
-        // Force the progress to 100% for the sender's UI.
-        if (this.pendingFolerMeta[folderName]) {
-          peerState.progressCallback?.(folderName, 1, 0);
-        }
-        break;
-      default:
-        this.log("warn", `Unknown signaling message type received`, {
-          type: message.type,
-          peerId,
-        });
-    }
+  public async sendString(content: string, peerId: string): Promise<void> {
+    return this.orchestrator.sendString(content, peerId);
   }
 
   public setProgressCallback(
     callback: (fileId: string, progress: number, speed: number) => void,
     peerId: string
   ): void {
-    this.getPeerState(peerId).progressCallback = callback;
-  }
-  // Respond to a file request by sending the file
-  private async handleFileRequest(
-    request: FileRequest,
-    peerId: string
-  ): Promise<void> {
-    const file = this.pendingFiles.get(request.fileId);
-    const offset = request.offset || 0;
-    this.log(
-      "log",
-      `Handling file request for ${request.fileId} from ${peerId} with offset ${offset}`
-    );
-    if (file) {
-      await this.sendSingleFile(file, peerId, offset);
-    } else {
-      this.fireError(`File not found for request`, {
-        fileId: request.fileId,
-        peerId,
-      });
-    }
-  }
-  // Modify the sendString method to be asynchronous
-  public async sendString(content: string, peerId: string): Promise<void> {
-    const chunks: string[] = [];
-    for (let i = 0; i < content.length; i += this.chunkSize) {
-      chunks.push(content.slice(i, i + this.chunkSize));
-    }
-
-    // First, send the metadata
-    await this.sendWithBackpressure(
-      JSON.stringify({
-        type: "stringMetadata",
-        length: content.length,
-      }),
-      peerId
-    );
-
-    // Send each chunk sequentially, using backpressure control
-    for (let i = 0; i < chunks.length; i++) {
-      const data = JSON.stringify({
-        type: "string",
-        chunk: chunks[i],
-        index: i,
-        total: chunks.length,
-      });
-      await this.sendWithBackpressure(data, peerId);
-    }
+    return this.orchestrator.setProgressCallback(callback, peerId);
   }
 
-  public sendFileMeta(files: CustomFile[], peerId?: string): void {
-    // Record the size of files belonging to a folder for progress calculation
-    files.forEach((file) => {
-      if (file.folderName) {
-        const folderId = file.folderName;
-        // folderName: {totalSize: 0, fileIds: []}
-        if (!this.pendingFolerMeta[folderId]) {
-          this.pendingFolerMeta[folderId] = { totalSize: 0, fileIds: [] };
-        }
-        const folderMeta = this.pendingFolerMeta[folderId];
-        const fileId = generateFileId(file);
-        if (!folderMeta.fileIds.includes(fileId)) {
-          // If the file has not been added yet
-          folderMeta.fileIds.push(fileId);
-          folderMeta.totalSize += file.size;
-        }
-      }
-    });
-    // Loop through and send the metadata for all files
-    const peers = peerId
-      ? [peerId]
-      : Array.from(this.webrtcConnection.peerConnections.keys());
-    peers.forEach((pId) => {
-      files.forEach((file) => {
-        const fileId = generateFileId(file);
-        this.pendingFiles.set(fileId, file);
-        const fileMeta = this.getFileMeta(file);
-        const metaDataString = JSON.stringify(fileMeta);
-
-        const sendResult = this.webrtcConnection.sendData(metaDataString, pId);
-        if (!sendResult) {
-          this.fireError("Failed to send file metadata", {
-            fileMeta,
-            peerId: pId,
-          });
-        }
-      });
-    });
+  public getTransferStats(peerId?: string) {
+    return this.orchestrator.getTransferStats(peerId);
   }
 
-  // Send a single file
-  private async sendSingleFile(
-    file: CustomFile,
-    peerId: string,
-    offset: number = 0
-  ): Promise<void> {
-    const fileId = generateFileId(file);
-    const peerState = this.getPeerState(peerId);
-
-    if (peerState.isSending) {
-      this.log(
-        "warn",
-        `Already sending a file to peer ${peerId}, request for ${file.name} ignored.`
-      );
-      return;
-    }
-
-    this.log(
-      "log",
-      `Starting to send single file: ${file.name} to ${peerId} from offset ${offset}`
-    );
-
-    // Reset state for the new transfer
-    peerState.isSending = true;
-    peerState.currentFolderName = file.folderName;
-    peerState.readOffset = offset; // Start reading from the given offset
-    peerState.bufferQueue = [];
-    peerState.isReading = false;
-    peerState.totalBytesSent[fileId] = offset; // Start counting sent bytes from the offset
-
-    try {
-      await this.processSendQueue(file, peerId);
-      this.finalizeSendFile(fileId, peerId);
-
-      await this.waitForTransferComplete(peerId); // Wait for transfer completion -- receiver confirmation
-    } catch (error: any) {
-      this.fireError(`Error sending file ${file.name}`, {
-        error: error.message,
-        fileId,
-        peerId,
-      });
-      this.abortFileSend(fileId, peerId);
-    }
+  public handlePeerReconnection(peerId: string): void {
+    this.orchestrator.handlePeerReconnection(peerId);
+    console.log(`[FileSender] Handled peer reconnection for ${peerId}`);
   }
 
-  private async waitForTransferComplete(peerId: string): Promise<void> {
-    const peerState = this.getPeerState(peerId);
-    while (peerState?.isSending) {
-      await new Promise((resolve) => setTimeout(resolve, 50));
-    }
-  }
-  private getFileMeta(file: CustomFile): fileMetadata {
-    const fileId = generateFileId(file);
-    return {
-      type: "fileMeta",
-      fileId,
-      name: file.name,
-      size: file.size,
-      fileType: file.type,
-      fullName: file.fullName,
-      folderName: file.folderName,
-    };
-  }
-
-  private async updateProgress(
-    byteLength: number,
-    fileId: string,
-    fileSize: number,
-    peerId: string
-  ): Promise<void> {
-    const peerState = this.getPeerState(peerId);
-    if (!peerState) return;
-
-    // Always update the individual file's progress first.
-    if (!peerState.totalBytesSent[fileId]) {
-      // This case should be handled by sendSingleFile's initialization
-      peerState.totalBytesSent[fileId] = 0;
-    }
-    peerState.totalBytesSent[fileId] += byteLength;
-
-    let progressFileId = fileId;
-    let currentBytes = peerState.totalBytesSent[fileId];
-    let totalSize = fileSize;
-
-    // If the file is part of a folder, recalculate the folder's progress.
-    if (peerState.currentFolderName) {
-      const folderId = peerState.currentFolderName;
-      const folderMeta = this.pendingFolerMeta[folderId];
-      progressFileId = folderId;
-      totalSize = folderMeta?.totalSize || 0;
-
-      // Recalculate folder progress from the sum of its files' progresses.
-      // This is more robust and correct for resumed transfers.
-      let folderTotalSent = 0;
-      if (folderMeta) {
-        folderMeta.fileIds.forEach((fId) => {
-          folderTotalSent += peerState.totalBytesSent[fId] || 0;
-        });
-      }
-      currentBytes = folderTotalSent;
-    }
-
-    this.speedCalculator.updateSendSpeed(peerId, currentBytes);
-    const speed = this.speedCalculator.getSendSpeed(peerId);
-    const progress = totalSize > 0 ? currentBytes / totalSize : 0;
-
-    peerState.progressCallback?.(progressFileId, progress, speed);
-  }
-
-  private async sendWithBackpressure(
-    data: string | ArrayBuffer,
-    peerId: string
-  ): Promise<void> {
-    const dataChannel = this.webrtcConnection.dataChannels.get(peerId);
-    if (!dataChannel) {
-      throw new Error("Data channel not found");
-    }
-
-    if (dataChannel.bufferedAmount > dataChannel.bufferedAmountLowThreshold) {
-      await new Promise<void>((resolve) => {
-        const listener = () => {
-          dataChannel.removeEventListener("bufferedamountlow", listener);
-          resolve();
-        };
-        dataChannel.addEventListener("bufferedamountlow", listener);
-      });
-    }
-
-    if (!this.webrtcConnection.sendData(data, peerId)) {
-      throw new Error("sendData failed");
-    }
-  }
-  //start sending file content
-  private async processSendQueue(
-    file: CustomFile,
-    peerId: string
-  ): Promise<void> {
-    const fileId = generateFileId(file);
-    const peerState = this.getPeerState(peerId);
-    const fileReader = new FileReader();
-
-    // The file object itself is the full file. Slicing happens here.
-    const fileToSend = file.slice(peerState.readOffset);
-    let relativeOffset = 0;
-
-    while (relativeOffset < fileToSend.size) {
-      if (!peerState.isSending) {
-        throw new Error("File sending was aborted.");
-      }
-
-      // Read chunks into buffer if not already reading and buffer is not full
-      if (
-        !peerState.isReading &&
-        peerState.bufferQueue.length < this.maxBufferSize
-      ) {
-        peerState.isReading = true;
-        const slice = fileToSend.slice(
-          relativeOffset,
-          relativeOffset + this.chunkSize
-        );
-        try {
-          const chunk = await this.readChunkAsArrayBuffer(fileReader, slice);
-          peerState.bufferQueue.push(chunk);
-          relativeOffset += chunk.byteLength;
-          peerState.readOffset += chunk.byteLength; // Also update the main offset
-        } catch (error: any) {
-          throw new Error(`File chunk reading failed: ${error.message}`);
-        } finally {
-          peerState.isReading = false;
-        }
-      }
-
-      // Send chunks from buffer
-      if (peerState.bufferQueue.length > 0) {
-        const chunk = peerState.bufferQueue.shift()!;
-        await this.sendWithBackpressure(chunk, peerId);
-        await this.updateProgress(chunk.byteLength, fileId, file.size, peerId);
-      } else if (peerState.isReading) {
-        // If buffer is empty but we are still reading, wait a bit
-        await new Promise((resolve) => setTimeout(resolve, 50));
-      } else if (relativeOffset < fileToSend.size) {
-        // Buffer is empty, not reading, but not done, so trigger a read
-        continue;
-      }
-    }
-    // Final progress update to 100%
-    if (!peerState.currentFolderName) {
-      this.getPeerState(peerId).progressCallback?.(fileId, 1, 0);
-    }
-  }
-
-  private readChunkAsArrayBuffer(
-    fileReader: FileReader,
-    blob: Blob
-  ): Promise<ArrayBuffer> {
-    return new Promise((resolve, reject) => {
-      fileReader.onload = (e) => {
-        // Ensure e.target.result is an ArrayBuffer
-        if (e.target?.result instanceof ArrayBuffer) {
-          resolve(e.target.result);
-        } else {
-          reject(new Error("Failed to read blob as ArrayBuffer"));
-        }
-      };
-      fileReader.onerror = () =>
-        reject(fileReader.error || new Error("Unknown FileReader error"));
-      fileReader.onabort = () => reject(new Error("File reading was aborted"));
-      fileReader.readAsArrayBuffer(blob);
-    });
-  }
-  //send fileEnd signal
-  private finalizeSendFile(fileId: string, peerId: string): void {
-    // this.log("log", `Finalizing file send for ${fileId} to ${peerId}`);
-    const endMessage = JSON.stringify({ type: "fileEnd", fileId });
-    if (!this.webrtcConnection.sendData(endMessage, peerId)) {
-      this.log("warn", `Failed to send fileEnd message for ${fileId}`);
-    }
-    // The isSending flag will be set to false upon receiving fileAck
-  }
-
-  private abortFileSend(fileId: string, peerId: string): void {
-    this.log("warn", `Aborting file send for ${fileId} to ${peerId}`);
-    const peerState = this.getPeerState(peerId);
-    peerState.isSending = false;
-    peerState.readOffset = 0;
-    peerState.bufferQueue = [];
-    peerState.isReading = false;
-    // Optionally, send an abort message to the receiver
+  public cleanup(): void {
+    return this.orchestrator.cleanup();
   }
 }
 

frontend/lib/fileUtils.ts

@@ -1,4 +1,5 @@
 import { CustomFile } from "@/types/webrtc";
+import { postLogToBackend } from "@/app/config/api";
 
 // Adaptively format the file size with units
 export const formatFileSize = (sizeInBytes: number): string => {
@@ -25,15 +26,45 @@ export const generateFileId = (file: CustomFile): string => {
 export const downloadAs = async (
   file: Blob | File,
   saveName: string
+): Promise<void> => {
+  // Check if file is empty
+  if (file.size === 0) {
+    postLogToBackend(
+      `[Download Debug] CRITICAL ERROR: downloadAs received a file with 0 size! This is the root cause of the 0-byte download issue.`
+    );
+    throw new Error("Cannot download file with 0 size");
+  }
+
+  try {
+    return await standardDownload(file, saveName);
+  } catch (error) {
+    postLogToBackend(`[Download Debug] ERROR in downloadAs: ${error}`);
+    throw error;
+  }
+};
+
+/**
+ * Standard download mechanism for all browsers
+ */
+const standardDownload = async (
+  file: Blob | File,
+  saveName: string
 ): Promise<void> => {
   const url = URL.createObjectURL(file);
-  const a = document.createElement("a");
-  a.href = url;
-  a.download = saveName;
-  document.body.appendChild(a);
-  a.click();
-  document.body.removeChild(a);
-  URL.revokeObjectURL(url);
+
+  try {
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = saveName;
+    a.style.display = "none";
+
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  } finally {
+    // Clean up the object URL after a delay to ensure download starts
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  }
 };
 
 export const traverseFileTree = async (

frontend/lib/receive/ChunkProcessor.ts

@@ -0,0 +1,329 @@
+import { EmbeddedChunkMeta } from "@/types/webrtc";
+import { ReceptionConfig } from "./ReceptionConfig";
+import { postLogToBackend } from "@/app/config/api";
+
+/**
+ * 🚀 Chunk processing result interface
+ */
+export interface ChunkProcessingResult {
+  chunkMeta: EmbeddedChunkMeta;
+  chunkData: ArrayBuffer;
+  absoluteChunkIndex: number;
+  relativeChunkIndex: number;
+}
+
+/**
+ * 🚀 Chunk processor
+ * Handles all data chunk processing, format conversion, and parsing
+ */
+export class ChunkProcessor {
+  /**
+   * Convert various binary data formats to ArrayBuffer
+   * Supports Blob, Uint8Array, and other formats for Firefox compatibility
+   */
+  async convertToArrayBuffer(data: any): Promise<ArrayBuffer | null> {
+    const originalType = Object.prototype.toString.call(data);
+
+    if (data instanceof ArrayBuffer) {
+      return data;
+    } else if (data instanceof Blob) {
+      try {
+        const arrayBuffer = await data.arrayBuffer();
+        if (data.size !== arrayBuffer.byteLength) {
+          if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+            postLogToBackend(
+              `[DEBUG] ⚠️ Blob size mismatch: ${data.size}→${arrayBuffer.byteLength}`
+            );
+          }
+        }
+        return arrayBuffer;
+      } catch (error) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(`[DEBUG] ❌ Blob conversion failed: ${error}`);
+        }
+        return null;
+      }
+    } else if (data instanceof Uint8Array || ArrayBuffer.isView(data)) {
+      try {
+        const uint8Array =
+          data instanceof Uint8Array
+            ? data
+            : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        const newArrayBuffer = new ArrayBuffer(uint8Array.length);
+        new Uint8Array(newArrayBuffer).set(uint8Array);
+        return newArrayBuffer;
+      } catch (error) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(`[DEBUG] ❌ TypedArray conversion failed: ${error}`);
+        }
+        return null;
+      }
+    } else {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ❌ Unknown data type: ${Object.prototype.toString.call(
+            data
+          )}`
+        );
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Parse embedded chunk packet
+   * Format: [4 bytes length] + [JSON metadata] + [actual chunk data]
+   */
+  parseEmbeddedChunkPacket(arrayBuffer: ArrayBuffer): {
+    chunkMeta: EmbeddedChunkMeta;
+    chunkData: ArrayBuffer;
+  } | null {
+    try {
+      // 1. Check minimum packet length
+      if (arrayBuffer.byteLength < ReceptionConfig.VALIDATION_CONFIG.MIN_PACKET_SIZE) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(
+            `[DEBUG] ❌ Invalid embedded packet - too small: ${arrayBuffer.byteLength}`
+          );
+        }
+        return null;
+      }
+
+      // 2. Read metadata length (4 bytes)
+      const lengthView = new Uint32Array(arrayBuffer, 0, 1);
+      const metaLength = lengthView[0];
+
+      // 3. Verify packet integrity
+      const expectedTotalLength = 4 + metaLength;
+      if (arrayBuffer.byteLength < expectedTotalLength) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(
+            `[DEBUG] ❌ Incomplete embedded packet - expected: ${expectedTotalLength}, got: ${arrayBuffer.byteLength}`
+          );
+        }
+        return null;
+      }
+
+      // 4. Extract metadata section
+      const metaBytes = new Uint8Array(arrayBuffer, 4, metaLength);
+      const metaJson = new TextDecoder().decode(metaBytes);
+      const chunkMeta: EmbeddedChunkMeta = JSON.parse(metaJson);
+
+      // 5. Extract actual chunk data section
+      const chunkDataStart = 4 + metaLength;
+      const chunkData = arrayBuffer.slice(chunkDataStart);
+
+      // 6. Verify chunk data size
+      if (chunkData.byteLength !== chunkMeta.chunkSize) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(
+            `[DEBUG] ⚠️ Chunk size mismatch - meta: ${chunkMeta.chunkSize}, actual: ${chunkData.byteLength}`
+          );
+        }
+      }
+
+      return { chunkMeta, chunkData };
+    } catch (error) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ❌ Failed to parse embedded packet: ${error}`
+        );
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Process received chunk and calculate indices
+   */
+  processReceivedChunk(
+    chunkMeta: EmbeddedChunkMeta,
+    chunkData: ArrayBuffer,
+    initialOffset: number
+  ): ChunkProcessingResult | null {
+    // Calculate indices
+    const absoluteChunkIndex = chunkMeta.chunkIndex; // Sender's absolute index
+    const startChunkIndex = ReceptionConfig.getChunkIndexFromOffset(initialOffset); // Resume start index
+    const relativeChunkIndex = absoluteChunkIndex - startChunkIndex; // Relative index in chunks array
+
+    // 🎯 Simplify debugging: Only record index mapping when boundary chunk
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING && (absoluteChunkIndex <= 2 || relativeChunkIndex <= 2)) {
+      postLogToBackend(
+        `[INDEX-MAP] abs:${absoluteChunkIndex}, start:${startChunkIndex}, rel:${relativeChunkIndex}`
+      );
+    }
+
+    return {
+      chunkMeta,
+      chunkData,
+      absoluteChunkIndex,
+      relativeChunkIndex,
+    };
+  }
+
+  /**
+   * Validate chunk against expected parameters
+   */
+  validateChunk(
+    chunkMeta: EmbeddedChunkMeta,
+    expectedFileId: string,
+    expectedChunksCount: number,
+    initialOffset: number
+  ): {
+    isValid: boolean;
+    errors: string[];
+  } {
+    const errors: string[] = [];
+
+    // Verify fileId match
+    if (chunkMeta.fileId !== expectedFileId) {
+      errors.push(`FileId mismatch - expected: ${expectedFileId}, got: ${chunkMeta.fileId}`);
+    }
+
+    // Validate chunk size
+    if (chunkMeta.chunkSize <= 0) {
+      errors.push(`Invalid chunk size: ${chunkMeta.chunkSize}`);
+    }
+
+    // Check if chunk index is reasonable
+    if (chunkMeta.chunkIndex < 0) {
+      errors.push(`Invalid chunk index: ${chunkMeta.chunkIndex}`);
+    }
+
+    // Validate total chunks (with resume consideration)
+    const startChunkIndex = ReceptionConfig.getChunkIndexFromOffset(initialOffset);
+    const calculatedExpected = chunkMeta.totalChunks - startChunkIndex;
+    
+    // 🎯 Simplify logging: Only record critical information when the number does not match
+    if (chunkMeta.totalChunks !== expectedChunksCount && calculatedExpected !== expectedChunksCount) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[CHUNK-COUNT-MISMATCH] fileTotal:${chunkMeta.totalChunks}, expected:${expectedChunksCount}, calculated:${calculatedExpected}`
+        );
+      }
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Check if chunk index is within valid range
+   */
+  isChunkIndexValid(
+    relativeChunkIndex: number,
+    expectedChunksCount: number
+  ): boolean {
+    return relativeChunkIndex >= 0 && relativeChunkIndex < expectedChunksCount;
+  }
+
+  /**
+   * Log chunk processing details (for debugging)
+   */
+  logChunkDetails(
+    result: ChunkProcessingResult,
+    expectedChunksCount: number,
+    writerExpectedIndex?: number
+  ): void {
+    if (!ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      return;
+    }
+
+    // 🎯 Simplify logging: Only record boundary chunk and abnormal cases
+    const { chunkMeta, absoluteChunkIndex, relativeChunkIndex } = result;
+    const isFirstFew = absoluteChunkIndex <= 3;
+    const isLastFew = relativeChunkIndex >= expectedChunksCount - 3;
+    
+    // 🔧 Fix: SequencedWriter expects absolute index, not relative index
+    const hasIndexMismatch = writerExpectedIndex !== undefined && absoluteChunkIndex !== writerExpectedIndex;
+
+    if (isFirstFew || isLastFew || hasIndexMismatch) {
+      postLogToBackend(
+        `[CHUNK-DETAIL] #${absoluteChunkIndex} rel:${relativeChunkIndex}${
+          hasIndexMismatch ? ` MISMATCH(writer expects:${writerExpectedIndex})` : ''
+        } size:${chunkMeta.chunkSize}`
+      );
+    }
+  }
+
+  /**
+   * Calculate completion statistics
+   */
+  calculateCompletionStats(
+    chunks: (ArrayBuffer | null)[],
+    expectedChunksCount: number,
+    expectedSize: number
+  ): {
+    sequencedCount: number;
+    currentTotalSize: number;
+    isSequencedComplete: boolean;
+    sizeComplete: boolean;
+    isDataComplete: boolean;
+  } {
+    // Calculate current actual total received size
+    const currentTotalSize = chunks.reduce((sum, chunk) => {
+      return sum + (chunk instanceof ArrayBuffer ? chunk.byteLength : 0);
+    }, 0);
+
+    // Count sequentially received chunks
+    let sequencedCount = 0;
+    for (let i = 0; i < expectedChunksCount; i++) {
+      if (chunks[i] instanceof ArrayBuffer) {
+        sequencedCount++;
+      }
+    }
+
+    const isSequencedComplete = sequencedCount === expectedChunksCount;
+    const sizeComplete = currentTotalSize >= expectedSize;
+    const isDataComplete = isSequencedComplete && sizeComplete;
+
+    return {
+      sequencedCount,
+      currentTotalSize,
+      isSequencedComplete,
+      sizeComplete,
+      isDataComplete,
+    };
+  }
+
+  /**
+   * Log completion check details (for debugging)
+   */
+  logCompletionCheck(
+    fileName: string,
+    stats: {
+      sequencedCount: number;
+      expectedChunksCount: number;
+      currentTotalSize: number;
+      expectedSize: number;
+      isDataComplete: boolean;
+    },
+    chunks: (ArrayBuffer | null)[],
+    initialOffset: number
+  ): void {
+    if (!ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      return;
+    }
+
+    const { sequencedCount, expectedChunksCount, currentTotalSize, expectedSize, isDataComplete } = stats;
+
+    // 🎯 Critical log 3: Only print final check results when complete
+    if (isDataComplete) {
+      const startChunkIndex = ReceptionConfig.getChunkIndexFromOffset(initialOffset);
+      const missingChunks = [];
+      
+      for (let i = 0; i < expectedChunksCount; i++) {
+        if (!chunks[i]) {
+          const absoluteIndex = startChunkIndex + i;
+          missingChunks.push(absoluteIndex);
+        }
+      }
+      
+      postLogToBackend(
+        `[FINAL-CHECK] File: ${fileName}, received: ${sequencedCount}/${expectedChunksCount}, sizeDiff: ${expectedSize - currentTotalSize}, missing: [${missingChunks.join(',')}]`
+      );
+    }
+  }
+}

frontend/lib/receive/FileAssembler.ts

@@ -0,0 +1,280 @@
+import { CustomFile, fileMetadata } from "@/types/webrtc";
+import { ReceptionConfig } from "./ReceptionConfig";
+import { postLogToBackend } from "@/app/config/api";
+
+const developmentEnv = process.env.NODE_ENV;
+
+/**
+ * 🚀 File assembly result interface
+ */
+export interface FileAssemblyResult {
+  file: CustomFile;
+  totalChunkSize: number;
+  validChunks: number;
+  storeUpdated: boolean;
+}
+
+/**
+ * 🚀 File assembler
+ * Handles in-memory file assembly and validation
+ */
+export class FileAssembler {
+  /**
+   * Assemble file from chunks in memory
+   */
+  async assembleFileFromChunks(
+    chunks: (ArrayBuffer | null)[],
+    meta: fileMetadata,
+    currentFolderName: string | null,
+    onFileReceived?: (file: CustomFile) => Promise<void>
+  ): Promise<FileAssemblyResult> {
+    // Validate and count chunks
+    let totalChunkSize = 0;
+    let validChunks = 0;
+
+    chunks.forEach((chunk, index) => {
+      if (chunk instanceof ArrayBuffer) {
+        validChunks++;
+        totalChunkSize += chunk.byteLength;
+      }
+    });
+
+    // Final verification
+    const sizeDifference = meta.size - totalChunkSize;
+    if (Math.abs(sizeDifference) > ReceptionConfig.VALIDATION_CONFIG.MAX_SIZE_DIFFERENCE_BYTES) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ❌ SIZE_MISMATCH - difference: ${sizeDifference} bytes (threshold: ${ReceptionConfig.VALIDATION_CONFIG.MAX_SIZE_DIFFERENCE_BYTES})`
+        );
+      }
+    }
+
+    // Create file blob from valid chunks
+    const validChunkBuffers = chunks.filter(
+      (chunk) => chunk instanceof ArrayBuffer
+    ) as ArrayBuffer[];
+
+    const fileBlob = new Blob(validChunkBuffers, {
+      type: meta.fileType,
+    });
+
+    // Create File object
+    const file = new File([fileBlob], meta.name, {
+      type: meta.fileType,
+    });
+
+    // Create CustomFile with additional properties
+    const customFile = Object.assign(file, {
+      fullName: meta.fullName,
+      folderName: currentFolderName,
+    }) as CustomFile;
+
+    // Store the file if callback is provided
+    let storeUpdated = false;
+    if (onFileReceived) {
+      await onFileReceived(customFile);
+      await Promise.resolve();
+      await new Promise<void>((resolve) => setTimeout(() => resolve(), 0));
+      storeUpdated = true;
+    }
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] ✅ File assembled - ${meta.name}, chunks: ${validChunks}/${chunks.length}, size: ${totalChunkSize}/${meta.size}, stored: ${storeUpdated}`
+      );
+    }
+
+    return {
+      file: customFile,
+      totalChunkSize,
+      validChunks,
+      storeUpdated,
+    };
+  }
+
+  /**
+   * Validate file assembly completeness
+   */
+  validateAssembly(
+    chunks: (ArrayBuffer | null)[],
+    expectedSize: number,
+    expectedChunksCount: number
+  ): {
+    isComplete: boolean;
+    validChunks: number;
+    totalSize: number;
+    missingChunks: number[];
+    sizeDifference: number;
+  } {
+    let totalSize = 0;
+    let validChunks = 0;
+    const missingChunks: number[] = [];
+
+    chunks.forEach((chunk, index) => {
+      if (chunk instanceof ArrayBuffer) {
+        validChunks++;
+        totalSize += chunk.byteLength;
+      } else {
+        missingChunks.push(index);
+      }
+    });
+
+    const sizeDifference = expectedSize - totalSize;
+    const isComplete = 
+      validChunks === expectedChunksCount && 
+      Math.abs(sizeDifference) <= ReceptionConfig.VALIDATION_CONFIG.MAX_SIZE_DIFFERENCE_BYTES;
+
+    return {
+      isComplete,
+      validChunks,
+      totalSize,
+      missingChunks,
+      sizeDifference,
+    };
+  }
+
+  /**
+   * Get assembly statistics for debugging
+   */
+  getAssemblyStats(chunks: (ArrayBuffer | null)[]): {
+    totalChunks: number;
+    validChunks: number;
+    nullChunks: number;
+    totalSize: number;
+    averageChunkSize: number;
+    firstNullIndex: number | null;
+    lastValidIndex: number | null;
+  } {
+    let validChunks = 0;
+    let totalSize = 0;
+    let firstNullIndex: number | null = null;
+    let lastValidIndex: number | null = null;
+
+    chunks.forEach((chunk, index) => {
+      if (chunk instanceof ArrayBuffer) {
+        validChunks++;
+        totalSize += chunk.byteLength;
+        lastValidIndex = index;
+      } else {
+        if (firstNullIndex === null) {
+          firstNullIndex = index;
+        }
+      }
+    });
+
+    const averageChunkSize = validChunks > 0 ? totalSize / validChunks : 0;
+
+    return {
+      totalChunks: chunks.length,
+      validChunks,
+      nullChunks: chunks.length - validChunks,
+      totalSize,
+      averageChunkSize,
+      firstNullIndex,
+      lastValidIndex,
+    };
+  }
+
+  /**
+   * Create file download URL for in-memory files
+   */
+  createDownloadUrl(file: File): string {
+    return URL.createObjectURL(file);
+  }
+
+  /**
+   * Revoke file download URL to free memory
+   */
+  revokeDownloadUrl(url: string): void {
+    URL.revokeObjectURL(url);
+  }
+
+  /**
+   * Get file type information
+   */
+  getFileTypeInfo(file: File): {
+    mimeType: string;
+    extension: string;
+    category: 'image' | 'video' | 'audio' | 'document' | 'archive' | 'other';
+  } {
+    const mimeType = file.type || 'application/octet-stream';
+    const extension = file.name.split('.').pop()?.toLowerCase() || '';
+
+    let category: 'image' | 'video' | 'audio' | 'document' | 'archive' | 'other' = 'other';
+
+    if (mimeType.startsWith('image/')) {
+      category = 'image';
+    } else if (mimeType.startsWith('video/')) {
+      category = 'video';
+    } else if (mimeType.startsWith('audio/')) {
+      category = 'audio';
+    } else if (
+      mimeType.includes('text/') ||
+      mimeType.includes('application/pdf') ||
+      mimeType.includes('application/msword') ||
+      mimeType.includes('application/vnd.openxmlformats')
+    ) {
+      category = 'document';
+    } else if (
+      mimeType.includes('zip') ||
+      mimeType.includes('rar') ||
+      mimeType.includes('tar') ||
+      mimeType.includes('gzip')
+    ) {
+      category = 'archive';
+    }
+
+    return {
+      mimeType,
+      extension,
+      category,
+    };
+  }
+
+  /**
+   * Estimate memory usage for file assembly
+   */
+  estimateMemoryUsage(chunks: (ArrayBuffer | null)[]): {
+    chunkMemoryUsage: number;
+    estimatedBlobMemory: number;
+    totalEstimatedMemory: number;
+  } {
+    const chunkMemoryUsage = chunks.reduce((sum, chunk) => {
+      return sum + (chunk instanceof ArrayBuffer ? chunk.byteLength : 0);
+    }, 0);
+
+    // Blob creation might temporarily double memory usage
+    const estimatedBlobMemory = chunkMemoryUsage;
+    const totalEstimatedMemory = chunkMemoryUsage + estimatedBlobMemory;
+
+    return {
+      chunkMemoryUsage,
+      estimatedBlobMemory,
+      totalEstimatedMemory,
+    };
+  }
+
+  /**
+   * Check if file should be assembled in memory or streamed to disk
+   */
+  shouldAssembleInMemory(
+    fileSize: number,
+    hasSaveDirectory: boolean,
+    availableMemory?: number
+  ): boolean {
+    // If we have a save directory and file is large, prefer disk
+    if (hasSaveDirectory && fileSize >= ReceptionConfig.FILE_CONFIG.LARGE_FILE_THRESHOLD) {
+      return false;
+    }
+
+    // If available memory is provided, check if we have enough
+    if (availableMemory !== undefined) {
+      // Need roughly 2x file size for assembly process
+      const requiredMemory = fileSize * 2;
+      return availableMemory > requiredMemory;
+    }
+
+    // Default: assemble in memory for smaller files
+    return fileSize < ReceptionConfig.FILE_CONFIG.LARGE_FILE_THRESHOLD;
+  }
+}

frontend/lib/receive/FileReceiveOrchestrator.ts

@@ -0,0 +1,713 @@
+import WebRTC_Recipient from "../webrtc_Recipient";
+import { CustomFile, fileMetadata } from "@/types/webrtc";
+import { ReceptionStateManager } from "./ReceptionStateManager";
+import { MessageProcessor, MessageProcessorDelegate } from "./MessageProcessor";
+import { ChunkProcessor } from "./ChunkProcessor";
+import {
+  StreamingFileWriter
+} from "./StreamingFileWriter";
+import { FileAssembler } from "./FileAssembler";
+import { ProgressReporter, ProgressCallback } from "./ProgressReporter";
+import { ReceptionConfig } from "./ReceptionConfig";
+import { ChunkRangeCalculator } from "@/lib/utils/ChunkRangeCalculator";
+import { postLogToBackend } from "@/app/config/api";
+
+/**
+ * 🚀 File receive orchestrator
+ * Main coordinator that integrates all reception modules
+ */
+export class FileReceiveOrchestrator implements MessageProcessorDelegate {
+  private stateManager: ReceptionStateManager;
+  private messageProcessor: MessageProcessor;
+  private chunkProcessor: ChunkProcessor;
+  private streamingFileWriter: StreamingFileWriter;
+  private fileAssembler: FileAssembler;
+  private progressReporter: ProgressReporter;
+
+  // Callbacks
+  public onFileMetaReceived: ((meta: fileMetadata) => void) | undefined =
+    undefined;
+  public onStringReceived: ((str: string) => void) | undefined = undefined;
+  public onFileReceived: ((file: CustomFile) => Promise<void>) | undefined =
+    undefined;
+
+  constructor(private webrtcConnection: WebRTC_Recipient) {
+    // Initialize all components
+    this.stateManager = new ReceptionStateManager();
+    this.chunkProcessor = new ChunkProcessor();
+    this.streamingFileWriter = new StreamingFileWriter();
+    this.fileAssembler = new FileAssembler();
+    this.progressReporter = new ProgressReporter(this.stateManager);
+    this.messageProcessor = new MessageProcessor(
+      this.stateManager,
+      webrtcConnection,
+      {
+        onFileMetaReceived: (meta: fileMetadata) => {
+          if (this.onFileMetaReceived) {
+            this.onFileMetaReceived(meta);
+          }
+        },
+        onStringReceived: (str: string) => {
+          if (this.onStringReceived) {
+            this.onStringReceived(str);
+          }
+        },
+        log: this.log.bind(this),
+      }
+    );
+
+    // Set up data handler
+    this.setupDataHandler();
+
+    this.log("log", "FileReceiveOrchestrator initialized");
+  }
+
+  // ===== Public API =====
+
+  /**
+   * Set progress callback
+   */
+  public setProgressCallback(callback: ProgressCallback): void {
+    this.progressReporter.setProgressCallback(callback);
+  }
+
+  /**
+   * Set save directory
+   */
+  public setSaveDirectory(directory: FileSystemDirectoryHandle): Promise<void> {
+    this.stateManager.setSaveDirectory(directory);
+    this.streamingFileWriter.setSaveDirectory(directory);
+    return Promise.resolve();
+  }
+
+  /**
+   * Request a single file from the peer
+   */
+  public async requestFile(fileId: string, singleFile = true): Promise<void> {
+    const activeReception = this.stateManager.getActiveFileReception();
+    if (activeReception) {
+      this.log("warn", "Another file reception is already in progress.");
+      return;
+    }
+
+    if (singleFile) {
+      this.stateManager.setCurrentFolderName(null);
+    }
+
+    const fileInfo = this.stateManager.getFileMetadata(fileId);
+    if (!fileInfo) {
+      this.fireError("File info not found for the requested fileId", {
+        fileId,
+      });
+      return;
+    }
+
+    const shouldSaveToDisk = ReceptionConfig.shouldSaveToDisk(
+      fileInfo.size,
+      this.streamingFileWriter.hasSaveDirectory()
+    );
+
+    // Set save type at the beginning to prevent race conditions
+    this.stateManager.setSaveType(fileInfo.fileId, shouldSaveToDisk);
+    const currentFolderName = this.stateManager.getCurrentFolderName();
+    if (currentFolderName) {
+      this.stateManager.setSaveType(currentFolderName, shouldSaveToDisk);
+    }
+
+    let offset = 0;
+    if (shouldSaveToDisk && this.streamingFileWriter.hasSaveDirectory()) {
+      try {
+        offset = await this.streamingFileWriter.getPartialFileSize(
+          fileInfo.name,
+          fileInfo.fullName
+        );
+
+        if (offset === fileInfo.size) {
+          this.log("log", "File already fully downloaded.", { fileId });
+          this.progressReporter.reportFileComplete(fileId);
+          return;
+        }
+        this.log("log", `Resuming file from offset: ${offset}`, { fileId });
+      } catch (e) {
+        this.log("log", "Partial file not found, starting from scratch.", {
+          fileId,
+        });
+        offset = 0;
+      }
+    }
+
+    const expectedChunksCount = ReceptionConfig.calculateExpectedChunks(
+      fileInfo.size,
+      offset
+    );
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      // 🎯 Critical log 2: Summary information for receiver - using unified chunk range calculation logic
+      const chunkRange = ChunkRangeCalculator.getChunkRange(
+        fileInfo.size,
+        offset,
+        ReceptionConfig.FILE_CONFIG.CHUNK_SIZE
+      );
+
+      postLogToBackend(
+        `[RECV-SUMMARY] File: ${fileInfo.name}, expected: ${expectedChunksCount}, calculated: ${chunkRange.totalChunks}, startChunk: ${chunkRange.startChunk}, endChunk: ${chunkRange.endChunk}, absoluteTotal: ${chunkRange.absoluteTotalChunks}`
+      );
+    }
+
+    const receptionPromise = this.stateManager.startFileReception(
+      fileInfo,
+      expectedChunksCount,
+      offset
+    );
+
+    if (shouldSaveToDisk) {
+      await this.createDiskWriteStream(fileInfo, offset);
+    }
+
+    // Send file request
+    const success = this.messageProcessor.sendFileRequest(fileId, offset);
+    if (!success) {
+      this.stateManager.failFileReception(
+        new Error("Failed to send file request")
+      );
+      return;
+    }
+
+    return receptionPromise;
+  }
+
+  /**
+   * Request all files belonging to a folder from the peer
+   */
+  public async requestFolder(folderName: string): Promise<void> {
+    const folderProgress = this.stateManager.getFolderProgress(folderName);
+    if (!folderProgress || folderProgress.fileIds.length === 0) {
+      this.log("warn", "No files found for the requested folder.", {
+        folderName,
+      });
+      return;
+    }
+
+    // Pre-calculate total size of already downloaded parts
+    let initialFolderReceivedSize = 0;
+    if (this.streamingFileWriter.hasSaveDirectory()) {
+      for (const fileId of folderProgress.fileIds) {
+        const fileInfo = this.stateManager.getFileMetadata(fileId);
+        if (fileInfo) {
+          try {
+            const partialSize =
+              await this.streamingFileWriter.getPartialFileSize(
+                fileInfo.name,
+                fileInfo.fullName
+              );
+            initialFolderReceivedSize += partialSize;
+          } catch (e) {
+            // File doesn't exist, so its size is 0
+          }
+        }
+      }
+    }
+
+    this.stateManager.setFolderReceivedSize(
+      folderName,
+      initialFolderReceivedSize
+    );
+    this.log(
+      "log",
+      `Requesting folder, initial received size: ${initialFolderReceivedSize}`,
+      { folderName }
+    );
+
+    this.stateManager.setCurrentFolderName(folderName);
+
+    for (const fileId of folderProgress.fileIds) {
+      try {
+        await this.requestFile(fileId, false);
+      } catch (error) {
+        this.fireError(
+          `Failed to receive file ${fileId} in folder ${folderName}`,
+          { error }
+        );
+        break;
+      }
+    }
+
+    this.stateManager.setCurrentFolderName(null);
+
+    // Send folder completion message
+    const completedFileIds = folderProgress.fileIds.filter(() => true); // Assume all succeeded
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] 📁 All files in folder completed - ${folderName}, files: ${completedFileIds.length}/${folderProgress.fileIds.length}`
+      );
+    }
+
+    this.messageProcessor.sendFolderReceiveComplete(
+      folderName,
+      completedFileIds,
+      true
+    );
+  }
+
+  // ===== MessageProcessorDelegate Implementation =====
+
+  // Note: These are implemented as properties, not methods, to avoid infinite recursion
+
+  public log(
+    level: "log" | "warn" | "error",
+    message: string,
+    context?: Record<string, any>
+  ): void {
+    const prefix = `[FileReceiveOrchestrator]`;
+    console[level](prefix, message, context || "");
+  }
+
+  // ===== Internal Methods =====
+
+  /**
+   * Set up data handler
+   */
+  private setupDataHandler(): void {
+    this.webrtcConnection.onDataReceived = async (data, peerId) => {
+      const binaryData = await this.messageProcessor.handleReceivedMessage(
+        data,
+        peerId
+      );
+
+      if (binaryData) {
+        // Handle binary chunk data
+        await this.handleBinaryChunkData(binaryData);
+      }
+    };
+  }
+
+  /**
+   * Handle binary chunk data
+   */
+  private async handleBinaryChunkData(data: any): Promise<void> {
+    const activeReception = this.stateManager.getActiveFileReception();
+    if (!activeReception) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ERROR: Received file chunk but no active file reception!`
+        );
+      }
+      this.fireError("Received a file chunk without an active file reception.");
+      return;
+    }
+
+    // Convert to ArrayBuffer
+    const arrayBuffer = await this.chunkProcessor.convertToArrayBuffer(data);
+    if (!arrayBuffer) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ERROR: Failed to convert binary data to ArrayBuffer`
+        );
+      }
+      this.fireError("Received unsupported binary data format", {
+        dataType: Object.prototype.toString.call(data),
+      });
+      return;
+    }
+
+    await this.handleEmbeddedChunkPacket(arrayBuffer);
+  }
+
+  /**
+   * Handle embedded chunk packet
+   */
+  private async handleEmbeddedChunkPacket(
+    arrayBuffer: ArrayBuffer
+  ): Promise<void> {
+    const parsed = this.chunkProcessor.parseEmbeddedChunkPacket(arrayBuffer);
+    if (!parsed) {
+      this.fireError("Failed to parse embedded chunk packet");
+      return;
+    }
+
+    const { chunkMeta, chunkData } = parsed;
+    const reception = this.stateManager.getActiveFileReception();
+    if (!reception) {
+      console.log(
+        `[FileReceiveOrchestrator] Ignoring chunk ${chunkMeta.chunkIndex} - file reception already closed`
+      );
+      return;
+    }
+
+    // Validate chunk
+    const validation = this.chunkProcessor.validateChunk(
+      chunkMeta,
+      reception.meta.fileId,
+      reception.expectedChunksCount,
+      reception.initialOffset
+    );
+
+    if (!validation.isValid) {
+      this.log("warn", "Chunk validation failed", {
+        errors: validation.errors,
+        chunkIndex: chunkMeta.chunkIndex,
+      });
+      return;
+    }
+
+    // Process chunk indices
+    const result = this.chunkProcessor.processReceivedChunk(
+      chunkMeta,
+      chunkData,
+      reception.initialOffset
+    );
+
+    if (!result) {
+      this.fireError("Failed to process received chunk");
+      return;
+    }
+
+    // Check if chunk index is valid
+    if (
+      !this.chunkProcessor.isChunkIndexValid(
+        result.relativeChunkIndex,
+        reception.expectedChunksCount
+      )
+    ) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-CHUNKS] ❌ Invalid relative chunk index - absolute:${result.absoluteChunkIndex}, relative:${result.relativeChunkIndex}, arraySize:${reception.chunks.length}`
+        );
+      }
+      return;
+    }
+
+    // Store chunk
+    reception.chunks[result.relativeChunkIndex] = result.chunkData;
+    reception.chunkSequenceMap.set(result.absoluteChunkIndex, true);
+    reception.receivedChunksCount++;
+
+    // Update progress
+    this.progressReporter.updateFileProgress(
+      result.chunkData.byteLength,
+      reception.meta.fileId,
+      reception.meta.size
+    );
+
+    // Handle disk writing if needed
+    if (reception.sequencedWriter) {
+      // 🔧 Fix: SequencedWriter uses absolute index, ensuring correct index is passed
+      this.chunkProcessor.logChunkDetails(
+        result,
+        reception.expectedChunksCount,
+        reception.sequencedWriter.expectedIndex
+      );
+
+      // ✅ Correctly use absolute index for disk writing
+      await reception.sequencedWriter.writeChunk(
+        result.absoluteChunkIndex,
+        result.chunkData
+      );
+    }
+
+    await this.checkAndAutoFinalize();
+  }
+
+  /**
+   * Check and auto-finalize file reception
+   */
+  private async checkAndAutoFinalize(): Promise<void> {
+    const reception = this.stateManager.getActiveFileReception();
+    if (!reception || reception.isFinalized) return;
+
+    const expectedSize = reception.meta.size - reception.initialOffset;
+    const stats = this.chunkProcessor.calculateCompletionStats(
+      reception.chunks,
+      reception.expectedChunksCount,
+      expectedSize
+    );
+
+    // Log completion check details
+    this.chunkProcessor.logCompletionCheck(
+      reception.meta.name,
+      {
+        sequencedCount: stats.sequencedCount,
+        expectedChunksCount: reception.expectedChunksCount,
+        currentTotalSize: stats.currentTotalSize,
+        expectedSize,
+        isDataComplete: stats.isDataComplete,
+      },
+      reception.chunks,
+      reception.initialOffset
+    );
+
+    if (stats.isDataComplete) {
+      reception.isFinalized = true;
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-COMPLETE] ✅ Starting finalization - isDataComplete:${stats.isDataComplete}`
+        );
+      }
+
+      try {
+        await this.finalizeFileReceive();
+        this.stateManager.completeFileReception();
+      } catch (error) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(`[DEBUG] ❌ Auto-finalize ERROR: ${error}`);
+        }
+        this.stateManager.failFileReception(error);
+      }
+    }
+  }
+
+  /**
+   * Finalize file reception
+   */
+  private async finalizeFileReceive(): Promise<void> {
+    const reception = this.stateManager.getActiveFileReception();
+    if (!reception) return;
+
+    if (reception.writeStream) {
+      await this.finalizeLargeFileReceive();
+    } else {
+      await this.finalizeMemoryFileReceive();
+    }
+  }
+
+  /**
+   * Finalize large file reception (disk-based)
+   */
+  private async finalizeLargeFileReceive(): Promise<void> {
+    const reception = this.stateManager.getActiveFileReception();
+    if (!reception?.writeStream || !reception.fileHandle) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ❌ Cannot finalize - missing writeStream:${!!reception?.writeStream} or fileHandle:${!!reception?.fileHandle}`
+        );
+      }
+      return;
+    }
+
+    try {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] 🚀 Starting finalization for ${reception.meta.name}`
+        );
+      }
+
+      // Finalize using StreamingFileWriter
+      if (reception.sequencedWriter && reception.writeStream) {
+        await this.streamingFileWriter.finalizeWrite(
+          reception.sequencedWriter,
+          reception.writeStream,
+          reception.meta.name
+        );
+      }
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ✅ LARGE_FILE finalized successfully - ${reception.meta.name}`
+        );
+      }
+
+      // 🆕 Send completion confirmation for large files
+      const stats = this.chunkProcessor.calculateCompletionStats(
+        reception.chunks,
+        reception.expectedChunksCount,
+        reception.meta.size - reception.initialOffset
+      );
+
+      this.messageProcessor.sendFileReceiveComplete(
+        reception.meta.fileId,
+        stats.currentTotalSize,
+        stats.sequencedCount,
+        true
+      );
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] 📤 LARGE_FILE completion confirmation sent - ${reception.meta.fileId}, size: ${stats.currentTotalSize}, chunks: ${stats.sequencedCount}`
+        );
+      }
+    } catch (error) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ❌ Error during finalization: ${error}`
+        );
+      }
+      this.fireError("Error finalizing large file", { error });
+    }
+  }
+
+  /**
+   * Finalize memory file reception
+   */
+  private async finalizeMemoryFileReceive(): Promise<void> {
+    const reception = this.stateManager.getActiveFileReception();
+    if (!reception) return;
+
+    const currentFolderName = this.stateManager.getCurrentFolderName();
+    const result = await this.fileAssembler.assembleFileFromChunks(
+      reception.chunks,
+      reception.meta,
+      currentFolderName,
+      this.onFileReceived
+    );
+
+    // Send completion confirmation
+    this.messageProcessor.sendFileReceiveComplete(
+      reception.meta.fileId,
+      result.totalChunkSize,
+      result.validChunks,
+      result.storeUpdated
+    );
+  }
+
+  /**
+   * Create disk write stream
+   */
+  private async createDiskWriteStream(
+    meta: fileMetadata,
+    offset: number
+  ): Promise<void> {
+    try {
+      const { fileHandle, writeStream, sequencedWriter } =
+        await this.streamingFileWriter.createWriteStream(
+          meta.name,
+          meta.fullName,
+          offset
+        );
+
+      this.stateManager.updateActiveFileReception({
+        fileHandle,
+        writeStream,
+        sequencedWriter,
+      });
+    } catch (err) {
+      this.fireError("Failed to create file on disk", {
+        err,
+        fileName: meta.name,
+      });
+    }
+  }
+
+  /**
+   * Error handling
+   */
+  private fireError(message: string, context?: Record<string, any>) {
+    if (this.webrtcConnection.fireError) {
+      // @ts-ignore
+      this.webrtcConnection.fireError(message, {
+        ...context,
+        component: "FileReceiveOrchestrator",
+      });
+    } else {
+      this.log("error", message, context);
+    }
+
+    const reception = this.stateManager.getActiveFileReception();
+    if (reception) {
+      // Clean up resources on error
+      if (reception.sequencedWriter) {
+        reception.sequencedWriter.close().catch((err: any) => {
+          this.log(
+            "error",
+            "Error closing sequenced writer during error cleanup",
+            { err }
+          );
+        });
+      }
+
+      this.stateManager.failFileReception(new Error(message));
+    }
+  }
+
+  // ===== Lifecycle Management =====
+
+  /**
+   * Graceful shutdown
+   */
+  public gracefulShutdown(reason: string = "CONNECTION_LOST"): void {
+    this.log("log", `Graceful shutdown initiated: ${reason}`);
+
+    const reception = this.stateManager.getActiveFileReception();
+    if (reception?.sequencedWriter && reception?.writeStream) {
+      this.log("log", "Attempting to gracefully close streams on shutdown.");
+
+      // Close sequenced writer and write stream
+      reception.sequencedWriter.close().catch((err: any) => {
+        this.log(
+          "error",
+          "Error closing sequenced writer during graceful shutdown",
+          { err }
+        );
+      });
+
+      reception.writeStream.close().catch((err: any) => {
+        this.log("error", "Error closing stream during graceful shutdown", {
+          err,
+        });
+      });
+    }
+
+    this.stateManager.gracefulCleanup();
+    this.log("log", "Graceful shutdown completed");
+  }
+
+  /**
+   * Force reset all internal states
+   */
+  public forceReset(): void {
+    this.log("log", "Force resetting FileReceiveOrchestrator state");
+
+    const reception = this.stateManager.getActiveFileReception();
+    if (reception?.sequencedWriter && reception?.writeStream) {
+      reception.sequencedWriter.close().catch(console.error);
+      reception.writeStream.close().catch(console.error);
+    }
+
+    this.stateManager.forceReset();
+    this.progressReporter.resetAllProgress();
+    this.log("log", "FileReceiveOrchestrator state force reset completed");
+  }
+
+  /**
+   * Get transfer statistics
+   */
+  public getTransferStats() {
+    return {
+      stateManager: this.stateManager.getStateStats(),
+      progressReporter: this.progressReporter.getProgressStats(),
+      messageProcessor: this.messageProcessor.getMessageStats(),
+    };
+  }
+
+  /**
+   * Get save type information (for backward compatibility)
+   */
+  public getSaveType(): Record<string, boolean> {
+    return this.stateManager.saveType;
+  }
+
+  /**
+   * Get pending files metadata (for backward compatibility)
+   */
+  public getPendingFilesMeta(): Map<string, fileMetadata> {
+    return this.stateManager.getAllFileMetadata();
+  }
+
+  /**
+   * Get folder progresses (for backward compatibility)
+   */
+  public getFolderProgresses(): Record<string, any> {
+    return this.stateManager.getAllFolderProgresses();
+  }
+
+  /**
+   * Clean up all resources
+   */
+  public cleanup(): void {
+    this.stateManager.gracefulCleanup();
+    this.progressReporter.cleanup();
+    this.messageProcessor.cleanup();
+    this.log("log", "FileReceiveOrchestrator cleaned up");
+  }
+}

frontend/lib/receive/MessageProcessor.ts

@@ -0,0 +1,302 @@
+import {
+  WebRTCMessage,
+  fileMetadata,
+  StringMetadata,
+  StringChunk,
+  FileRequest,
+  FileReceiveComplete,
+  FolderReceiveComplete,
+  FileHandlers,
+} from "@/types/webrtc";
+import { ReceptionStateManager } from "./ReceptionStateManager";
+import { ReceptionConfig } from "./ReceptionConfig";
+import { postLogToBackend } from "@/app/config/api";
+import WebRTC_Recipient from "../webrtc_Recipient";
+
+const developmentEnv = process.env.NODE_ENV;
+
+/**
+ * 🚀 Message processor delegate interface
+ */
+export interface MessageProcessorDelegate {
+  onFileMetaReceived?: (meta: fileMetadata) => void;
+  onStringReceived?: (str: string) => void;
+  log(level: "log" | "warn" | "error", message: string, context?: Record<string, any>): void;
+}
+
+/**
+ * 🚀 Message processor
+ * Handles WebRTC message routing, processing, and communication
+ */
+export class MessageProcessor {
+  private fileHandlers: FileHandlers;
+
+  constructor(
+    private stateManager: ReceptionStateManager,
+    private webrtcConnection: WebRTC_Recipient,
+    private delegate: MessageProcessorDelegate
+  ) {
+    this.fileHandlers = {
+      string: this.handleReceivedStringChunk.bind(this),
+      stringMetadata: this.handleStringMetadata.bind(this),
+      fileMeta: this.handleFileMetadata.bind(this),
+    };
+  }
+
+  /**
+   * Handle received WebRTC message
+   */
+  async handleReceivedMessage(
+    data: string | ArrayBuffer | any,
+    peerId: string
+  ): Promise<ArrayBuffer | null> {
+    this.stateManager.setCurrentPeerId(peerId);
+
+    if (typeof data === "string") {
+      try {
+        const parsedData = JSON.parse(data) as WebRTCMessage;
+        const handler = this.fileHandlers[parsedData.type as keyof FileHandlers];
+        
+        if (handler) {
+          await handler(parsedData as any, peerId);
+        } else {
+          this.delegate.log(
+            "warn",
+            `Handler not found for message type: ${parsedData.type}`,
+            { peerId }
+          );
+        }
+        return null; // String messages don't return binary data
+      } catch (error) {
+        this.delegate.log("error", "Error parsing received JSON data", { error, peerId });
+        return null;
+      }
+    } else {
+      // Return binary data for chunk processing
+      return data;
+    }
+  }
+
+  /**
+   * Handle file metadata message
+   */
+  private handleFileMetadata(metadata: fileMetadata): void {
+    const isNewMetadata = this.stateManager.addFileMetadata(metadata);
+    
+    if (!isNewMetadata) {
+      return; // Ignore if already received
+    }
+
+    if (this.delegate.onFileMetaReceived) {
+      this.delegate.onFileMetaReceived(metadata);
+    } else {
+      this.delegate.log(
+        "error",
+        "onFileMetaReceived callback not set",
+        { fileId: metadata.fileId }
+      );
+    }
+  }
+
+  /**
+   * Handle string metadata message
+   */
+  private handleStringMetadata(metadata: StringMetadata): void {
+    this.stateManager.startStringReception(metadata.length);
+  }
+
+  /**
+   * Handle received string chunk message
+   */
+  private handleReceivedStringChunk(data: StringChunk): void {
+    const activeStringReception = this.stateManager.getActiveStringReception();
+    if (!activeStringReception) {
+      this.delegate.log("warn", "Received string chunk without active reception");
+      return;
+    }
+
+    this.stateManager.updateStringReceptionChunk(data.index, data.chunk);
+
+    // Check if string reception is complete
+    if (activeStringReception.receivedChunks === data.total) {
+      const fullString = this.stateManager.completeStringReception();
+      if (fullString && this.delegate.onStringReceived) {
+        this.delegate.onStringReceived(fullString);
+      }
+    }
+  }
+
+  /**
+   * Send file request message
+   */
+  sendFileRequest(fileId: string, offset: number = 0): boolean {
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ERROR: Cannot send fileRequest - no peerId available!`
+        );
+      }
+      return false;
+    }
+
+    const request: FileRequest = { type: "fileRequest", fileId, offset };
+    const success = this.webrtcConnection.sendData(JSON.stringify(request), peerId);
+    
+    if (success) {
+      this.delegate.log("log", "Sent fileRequest", { request, peerId });
+    } else {
+      this.delegate.log("error", "Failed to send fileRequest", { request, peerId });
+    }
+    
+    return success;
+  }
+
+  /**
+   * Send file receive complete message
+   */
+  sendFileReceiveComplete(
+    fileId: string,
+    receivedSize: number,
+    receivedChunks: number,
+    storeUpdated: boolean
+  ): boolean {
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) {
+      this.delegate.log("warn", "Cannot send file receive complete - no peer ID");
+      return false;
+    }
+
+    const completeMessage: FileReceiveComplete = {
+      type: "fileReceiveComplete",
+      fileId,
+      receivedSize,
+      receivedChunks,
+      storeUpdated,
+    };
+
+    const success = this.webrtcConnection.sendData(
+      JSON.stringify(completeMessage),
+      peerId
+    );
+
+    if (success) {
+      this.delegate.log("log", "Sent file receive complete", {
+        fileId,
+        receivedSize,
+        receivedChunks,
+        storeUpdated,
+      });
+    } else {
+      this.delegate.log("error", "Failed to send file receive complete", {
+        fileId,
+        peerId,
+      });
+    }
+
+    return success;
+  }
+
+  /**
+   * Send folder receive complete message
+   */
+  sendFolderReceiveComplete(
+    folderName: string,
+    completedFileIds: string[],
+    allStoreUpdated: boolean
+  ): boolean {
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) {
+      this.delegate.log("warn", "Cannot send folder receive complete - no peer ID");
+      return false;
+    }
+
+    const completeMessage: FolderReceiveComplete = {
+      type: "folderReceiveComplete",
+      folderName,
+      completedFileIds,
+      allStoreUpdated,
+    };
+
+    const success = this.webrtcConnection.sendData(
+      JSON.stringify(completeMessage),
+      peerId
+    );
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] 📤 Sent folderReceiveComplete - folderName: ${folderName}, completedFiles: ${completedFileIds.length}, allStoreUpdated: ${allStoreUpdated}, success: ${success}`
+      );
+    }
+
+    if (success) {
+      this.delegate.log("log", "Sent folder receive complete", {
+        folderName,
+        completedFiles: completedFileIds.length,
+        allStoreUpdated,
+      });
+    } else {
+      this.delegate.log("error", "Failed to send folder receive complete", {
+        folderName,
+        peerId,
+      });
+    }
+
+    return success;
+  }
+
+  /**
+   * Add Firefox compatibility delay
+   */
+  async addFirefoxDelay(): Promise<void> {
+    await new Promise((resolve) => 
+      setTimeout(resolve, ReceptionConfig.NETWORK_CONFIG.FIREFOX_COMPATIBILITY_DELAY)
+    );
+  }
+
+  /**
+   * Get message processing statistics
+   */
+  getMessageStats(): {
+    handledMessages: number;
+    lastMessageTime: number | null;
+    currentPeerId: string;
+  } {
+    return {
+      handledMessages: 0, // TODO: Implement message counting if needed
+      lastMessageTime: null, // TODO: Record last message time if needed
+      currentPeerId: this.stateManager.getCurrentPeerId(),
+    };
+  }
+
+  /**
+   * Check if connection is available
+   */
+  isConnectionAvailable(): boolean {
+    const peerId = this.stateManager.getCurrentPeerId();
+    return !!peerId && !!this.webrtcConnection;
+  }
+
+  /**
+   * Get current peer connection info
+   */
+  getPeerConnectionInfo(): {
+    peerId: string;
+    isConnected: boolean;
+  } {
+    const peerId = this.stateManager.getCurrentPeerId();
+    return {
+      peerId,
+      isConnected: this.isConnectionAvailable(),
+    };
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup(): void {
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend("[DEBUG] 🧹 MessageProcessor cleaned up");
+    }
+  }
+}

frontend/lib/receive/ProgressReporter.ts

@@ -0,0 +1,309 @@
+import { SpeedCalculator } from "@/lib/speedCalculator";
+import { ReceptionStateManager } from "./ReceptionStateManager";
+import { ReceptionConfig } from "./ReceptionConfig";
+import { postLogToBackend } from "@/app/config/api";
+
+const developmentEnv = process.env.NODE_ENV;
+
+/**
+ * 🚀 Progress callback type
+ */
+export type ProgressCallback = (fileId: string, progress: number, speed: number) => void;
+
+/**
+ * 🚀 Progress statistics interface
+ */
+export interface ProgressStats {
+  fileProgress: Record<string, number>;
+  folderProgress: Record<string, number>;
+  currentSpeed: number;
+  averageSpeed: number;
+  totalBytesReceived: number;
+  estimatedTimeRemaining: number | null;
+}
+
+/**
+ * 🚀 Progress reporter
+ * Handles progress calculation, speed tracking, and progress callback management
+ */
+export class ProgressReporter {
+  private speedCalculator: SpeedCalculator;
+  private progressCallback: ProgressCallback | null = null;
+
+  // Progress tracking
+  private fileProgressMap = new Map<string, number>();
+  private folderProgressMap = new Map<string, number>();
+  private lastProgressUpdate = new Map<string, number>();
+
+  constructor(private stateManager: ReceptionStateManager) {
+    this.speedCalculator = new SpeedCalculator();
+  }
+
+  /**
+   * Set progress callback
+   */
+  setProgressCallback(callback: ProgressCallback): void {
+    this.progressCallback = callback;
+  }
+
+  /**
+   * Update file reception progress
+   */
+  updateFileProgress(
+    byteLength: number,
+    fileId: string,
+    fileSize: number
+  ): void {
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) return;
+
+    const activeReception = this.stateManager.getActiveFileReception();
+    if (!activeReception) return;
+
+    // Update received size
+    activeReception.receivedSize += byteLength;
+    const totalReceived = activeReception.initialOffset + activeReception.receivedSize;
+
+    const currentFolderName = this.stateManager.getCurrentFolderName();
+
+    if (currentFolderName) {
+      // Update folder progress
+      this.updateFolderProgress(currentFolderName, byteLength, peerId);
+    } else {
+      // Update individual file progress
+      this.speedCalculator.updateSendSpeed(peerId, totalReceived);
+      const speed = this.speedCalculator.getSendSpeed(peerId);
+      const progress = fileSize > 0 ? totalReceived / fileSize : 0;
+
+      // Store progress for statistics
+      this.fileProgressMap.set(fileId, progress);
+
+      // Throttle progress callbacks to avoid overwhelming the UI
+      const now = Date.now();
+      const lastUpdate = this.lastProgressUpdate.get(fileId) || 0;
+      const shouldUpdate = now - lastUpdate > 100; // Update at most every 100ms
+
+      if (shouldUpdate || progress >= 1) {
+        this.progressCallback?.(fileId, progress, speed);
+        this.lastProgressUpdate.set(fileId, now);
+      }
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_PROGRESS_LOGGING && progress >= 1) {
+        postLogToBackend(
+          `[DEBUG] 📈 File progress 100% - ${fileId}, speed: ${(speed / 1024 / 1024).toFixed(1)}MB/s`
+        );
+      }
+    }
+  }
+
+  /**
+   * Update folder reception progress
+   */
+  private updateFolderProgress(
+    folderName: string,
+    byteLength: number,
+    peerId: string
+  ): void {
+    // Update folder received size in state manager
+    this.stateManager.updateFolderReceivedSize(folderName, byteLength);
+    
+    const folderProgress = this.stateManager.getFolderProgress(folderName);
+    if (!folderProgress) return;
+
+    this.speedCalculator.updateSendSpeed(peerId, folderProgress.receivedSize);
+    const speed = this.speedCalculator.getSendSpeed(peerId);
+    const progress = folderProgress.totalSize > 0 
+      ? folderProgress.receivedSize / folderProgress.totalSize 
+      : 0;
+
+    // Store progress for statistics
+    this.folderProgressMap.set(folderName, progress);
+
+    // Throttle folder progress callbacks
+    const now = Date.now();
+    const lastUpdate = this.lastProgressUpdate.get(folderName) || 0;
+    const shouldUpdate = now - lastUpdate > 200; // Update folders less frequently
+
+    if (shouldUpdate || progress >= 1) {
+      this.progressCallback?.(folderName, progress, speed);
+      this.lastProgressUpdate.set(folderName, now);
+    }
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_PROGRESS_LOGGING && progress >= 1) {
+      postLogToBackend(
+        `[DEBUG] 📈 Folder progress 100% - ${folderName}, speed: ${(speed / 1024 / 1024).toFixed(1)}MB/s`
+      );
+    }
+  }
+
+  /**
+   * Report file completion (100% progress)
+   */
+  reportFileComplete(fileId: string): void {
+    if (!this.progressCallback) return;
+
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) return;
+
+    // Get final speed and report 100% progress
+    const speed = this.speedCalculator.getSendSpeed(peerId);
+    this.progressCallback(fileId, 1, speed);
+    this.fileProgressMap.set(fileId, 1);
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_PROGRESS_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] ✅ File completion reported - ${fileId}, final speed: ${(speed / 1024 / 1024).toFixed(1)}MB/s`
+      );
+    }
+  }
+
+  /**
+   * Report folder completion (100% progress)
+   */
+  reportFolderComplete(folderName: string): void {
+    if (!this.progressCallback) return;
+
+    const peerId = this.stateManager.getCurrentPeerId();
+    if (!peerId) return;
+
+    // Get final speed and report 100% progress
+    const speed = this.speedCalculator.getSendSpeed(peerId);
+    this.progressCallback(folderName, 1, speed);
+    this.folderProgressMap.set(folderName, 1);
+
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_PROGRESS_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] ✅ Folder completion reported - ${folderName}, final speed: ${(speed / 1024 / 1024).toFixed(1)}MB/s`
+      );
+    }
+  }
+
+  /**
+   * Get current progress for a file or folder
+   */
+  getCurrentProgress(id: string): number {
+    return this.fileProgressMap.get(id) || this.folderProgressMap.get(id) || 0;
+  }
+
+  /**
+   * Get current speed for peer
+   */
+  getCurrentSpeed(): number {
+    const peerId = this.stateManager.getCurrentPeerId();
+    return peerId ? this.speedCalculator.getSendSpeed(peerId) : 0;
+  }
+
+  /**
+   * Get detailed progress statistics
+   */
+  getProgressStats(): ProgressStats {
+    const peerId = this.stateManager.getCurrentPeerId();
+    const currentSpeed = peerId ? this.speedCalculator.getSendSpeed(peerId) : 0;
+    const averageSpeed = currentSpeed; // SpeedCalculator doesn't have getAverageSpeed method
+
+    // Calculate total bytes received
+    let totalBytesReceived = 0;
+    const activeReception = this.stateManager.getActiveFileReception();
+    if (activeReception) {
+      totalBytesReceived = activeReception.initialOffset + activeReception.receivedSize;
+    }
+
+    // Estimate time remaining
+    let estimatedTimeRemaining: number | null = null;
+    if (activeReception && currentSpeed > 0) {
+      const remainingBytes = activeReception.meta.size - totalBytesReceived;
+      if (remainingBytes > 0) {
+        estimatedTimeRemaining = remainingBytes / currentSpeed; // seconds
+      }
+    }
+
+    const fileProgress: Record<string, number> = {};
+    this.fileProgressMap.forEach((progress, fileId) => {
+      fileProgress[fileId] = progress;
+    });
+
+    const folderProgress: Record<string, number> = {};
+    this.folderProgressMap.forEach((progress, folderName) => {
+      folderProgress[folderName] = progress;
+    });
+
+    return {
+      fileProgress,
+      folderProgress,
+      currentSpeed,
+      averageSpeed,
+      totalBytesReceived,
+      estimatedTimeRemaining,
+    };
+  }
+
+  /**
+   * Reset progress for a specific file or folder
+   */
+  resetProgress(id: string): void {
+    this.fileProgressMap.delete(id);
+    this.folderProgressMap.delete(id);
+    this.lastProgressUpdate.delete(id);
+  }
+
+  /**
+   * Reset all progress data
+   */
+  resetAllProgress(): void {
+    this.fileProgressMap.clear();
+    this.folderProgressMap.clear();
+    this.lastProgressUpdate.clear();
+    
+    // Reset speed calculator for current peer
+    // Note: SpeedCalculator doesn't have resetSpeed method, so we create a new instance
+    this.speedCalculator = new SpeedCalculator();
+  }
+
+  /**
+   * Get progress update frequency (for debugging)
+   */
+  getUpdateFrequency(id: string): number {
+    const lastUpdate = this.lastProgressUpdate.get(id);
+    return lastUpdate ? Date.now() - lastUpdate : 0;
+  }
+
+  /**
+   * Check if progress should be throttled
+   */
+  shouldThrottleProgress(id: string, isFolder: boolean = false): boolean {
+    const now = Date.now();
+    const lastUpdate = this.lastProgressUpdate.get(id) || 0;
+    const threshold = isFolder ? 200 : 100; // Folders update less frequently
+    return now - lastUpdate < threshold;
+  }
+
+  /**
+   * Force progress update (bypass throttling)
+   */
+  forceProgressUpdate(id: string, progress: number): void {
+    if (!this.progressCallback) return;
+
+    const speed = this.getCurrentSpeed();
+    this.progressCallback(id, progress, speed);
+    this.lastProgressUpdate.set(id, Date.now());
+
+    // Update internal maps
+    if (this.fileProgressMap.has(id)) {
+      this.fileProgressMap.set(id, progress);
+    } else if (this.folderProgressMap.has(id)) {
+      this.folderProgressMap.set(id, progress);
+    }
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup(): void {
+    this.resetAllProgress();
+    this.progressCallback = null;
+    
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_PROGRESS_LOGGING) {
+      postLogToBackend("[DEBUG] 🧹 ProgressReporter cleaned up");
+    }
+  }
+}

frontend/lib/receive/ReceptionConfig.ts

@@ -0,0 +1,74 @@
+/**
+ * 🚀 Reception configuration management
+ * Centralized configuration for file reception parameters
+ */
+
+export class ReceptionConfig {
+  // File size thresholds
+  static readonly FILE_CONFIG = {
+    LARGE_FILE_THRESHOLD: 1 * 1024 * 1024 * 1024, // 1GB - files larger than this will be saved to disk
+    CHUNK_SIZE: 65536, // 64KB standard chunk size
+  };
+
+  // Buffer management
+  static readonly BUFFER_CONFIG = {
+    MAX_BUFFER_SIZE: 100, // Buffer up to 100 chunks (approximately 6.4MB)
+    SEQUENTIAL_FLUSH_THRESHOLD: 10, // Start flushing when this many sequential chunks are available
+  };
+
+  // Performance and debugging
+  static readonly DEBUG_CONFIG = {
+    ENABLE_CHUNK_LOGGING: process.env.NODE_ENV === "development",
+    ENABLE_PROGRESS_LOGGING: process.env.NODE_ENV === "development",
+    PROGRESS_LOG_INTERVAL: 500, // Log progress every N chunks
+    COMPLETION_CHECK_INTERVAL: 100, // Check completion every N ms
+  };
+
+  // Network and timing
+  static readonly NETWORK_CONFIG = {
+    FIREFOX_COMPATIBILITY_DELAY: 10, // ms delay for Firefox compatibility
+    FINALIZATION_TIMEOUT: 30000, // 30s timeout for file finalization
+    GRACEFUL_SHUTDOWN_TIMEOUT: 5000, // 5s timeout for graceful shutdown
+  };
+
+  // Validation thresholds
+  static readonly VALIDATION_CONFIG = {
+    MAX_SIZE_DIFFERENCE_BYTES: 1024, // Allow up to 1KB size difference for validation
+    MIN_PACKET_SIZE: 4, // Minimum embedded packet size (4 bytes for length header)
+  };
+
+  /**
+   * Get chunk index from file offset
+   */
+  static getChunkIndexFromOffset(offset: number): number {
+    return Math.floor(offset / this.FILE_CONFIG.CHUNK_SIZE);
+  }
+
+  /**
+   * Get file offset from chunk index
+   */
+  static getOffsetFromChunkIndex(chunkIndex: number): number {
+    return chunkIndex * this.FILE_CONFIG.CHUNK_SIZE;
+  }
+
+  /**
+   * Calculate expected chunks count for file size and offset
+   */
+  static calculateExpectedChunks(fileSize: number, startOffset: number = 0): number {
+    return Math.ceil((fileSize - startOffset) / this.FILE_CONFIG.CHUNK_SIZE);
+  }
+
+  /**
+   * Calculate total chunks in file
+   */
+  static calculateTotalChunks(fileSize: number): number {
+    return Math.ceil(fileSize / this.FILE_CONFIG.CHUNK_SIZE);
+  }
+
+  /**
+   * Check if file should be saved to disk
+   */
+  static shouldSaveToDisk(fileSize: number, hasSaveDirectory: boolean): boolean {
+    return hasSaveDirectory || fileSize >= this.FILE_CONFIG.LARGE_FILE_THRESHOLD;
+  }
+}

frontend/lib/receive/ReceptionStateManager.ts

@@ -0,0 +1,358 @@
+import {
+  fileMetadata,
+  FolderProgress,
+  CurrentString,
+  CustomFile,
+} from "@/types/webrtc";
+
+/**
+ * 🚀 Active file reception state interface
+ */
+export interface ActiveFileReception {
+  meta: fileMetadata;
+  chunks: (ArrayBuffer | null)[];
+  receivedSize: number;
+  initialOffset: number;
+  fileHandle: FileSystemFileHandle | null;
+  writeStream: FileSystemWritableFileStream | null;
+  sequencedWriter: any | null; // Will be typed properly when StreamingFileWriter is implemented
+  completionNotifier: {
+    resolve: () => void;
+    reject: (reason?: any) => void;
+  };
+  receivedChunksCount: number;
+  expectedChunksCount: number;
+  chunkSequenceMap: Map<number, boolean>;
+  isFinalized?: boolean;
+}
+
+/**
+ * 🚀 Reception state management
+ * Centrally manages all file reception state data
+ */
+export class ReceptionStateManager {
+  // File metadata management
+  private pendingFilesMeta = new Map<string, fileMetadata>();
+  
+  // Folder progress tracking
+  private folderProgresses: Record<string, FolderProgress> = {};
+  
+  // Save type configuration (fileId/folderName -> isSavedToDisk)
+  public saveType: Record<string, boolean> = {};
+  
+  // Active transfer states
+  private activeFileReception: ActiveFileReception | null = null;
+  private activeStringReception: CurrentString | null = null;
+  private currentFolderName: string | null = null;
+  
+  // Peer information
+  private currentPeerId: string = "";
+  private saveDirectory: FileSystemDirectoryHandle | null = null;
+
+  // ===== File Metadata Management =====
+
+  /**
+   * Add file metadata
+   */
+  public addFileMetadata(metadata: fileMetadata): boolean {
+    if (this.pendingFilesMeta.has(metadata.fileId)) {
+      return false; // Already exists
+    }
+    
+    this.pendingFilesMeta.set(metadata.fileId, metadata);
+    
+    // Update folder progress if this file belongs to a folder
+    if (metadata.folderName) {
+      this.addFileToFolder(metadata.folderName, metadata.fileId, metadata.size);
+    }
+    
+    return true; // New metadata added
+  }
+
+  /**
+   * Get file metadata by ID
+   */
+  public getFileMetadata(fileId: string): fileMetadata | undefined {
+    return this.pendingFilesMeta.get(fileId);
+  }
+
+  /**
+   * Get all pending file metadata
+   */
+  public getAllFileMetadata(): Map<string, fileMetadata> {
+    return new Map(this.pendingFilesMeta);
+  }
+
+  /**
+   * Remove file metadata
+   */
+  public removeFileMetadata(fileId: string): void {
+    this.pendingFilesMeta.delete(fileId);
+  }
+
+  // ===== Folder Progress Management =====
+
+  /**
+   * Add file to folder progress tracking
+   */
+  private addFileToFolder(folderName: string, fileId: string, fileSize: number): void {
+    if (!this.folderProgresses[folderName]) {
+      this.folderProgresses[folderName] = {
+        totalSize: 0,
+        receivedSize: 0,
+        fileIds: [],
+      };
+    }
+
+    const folderProgress = this.folderProgresses[folderName];
+    if (!folderProgress.fileIds.includes(fileId)) {
+      folderProgress.fileIds.push(fileId);
+      folderProgress.totalSize += fileSize;
+    }
+  }
+
+  /**
+   * Get folder progress
+   */
+  public getFolderProgress(folderName: string): FolderProgress | undefined {
+    return this.folderProgresses[folderName];
+  }
+
+  /**
+   * Update folder received size
+   */
+  public updateFolderReceivedSize(folderName: string, additionalBytes: number): void {
+    const folderProgress = this.folderProgresses[folderName];
+    if (folderProgress) {
+      folderProgress.receivedSize += additionalBytes;
+    }
+  }
+
+  /**
+   * Set folder received size (for resume scenarios)
+   */
+  public setFolderReceivedSize(folderName: string, totalReceivedSize: number): void {
+    const folderProgress = this.folderProgresses[folderName];
+    if (folderProgress) {
+      folderProgress.receivedSize = totalReceivedSize;
+    }
+  }
+
+  /**
+   * Get all folder progresses
+   */
+  public getAllFolderProgresses(): Record<string, FolderProgress> {
+    return { ...this.folderProgresses };
+  }
+
+  // ===== Active File Reception Management =====
+
+  /**
+   * Start active file reception
+   */
+  public startFileReception(
+    meta: fileMetadata,
+    expectedChunksCount: number,
+    initialOffset: number = 0
+  ): Promise<void> {
+    if (this.activeFileReception) {
+      throw new Error("Another file reception is already in progress");
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      this.activeFileReception = {
+        meta,
+        chunks: new Array(expectedChunksCount).fill(null),
+        receivedSize: 0,
+        initialOffset,
+        fileHandle: null,
+        writeStream: null,
+        sequencedWriter: null,
+        completionNotifier: { resolve, reject },
+        receivedChunksCount: 0,
+        expectedChunksCount,
+        chunkSequenceMap: new Map<number, boolean>(),
+        isFinalized: false,
+      };
+    });
+  }
+
+  /**
+   * Get active file reception
+   */
+  public getActiveFileReception(): ActiveFileReception | null {
+    return this.activeFileReception;
+  }
+
+  /**
+   * Update active file reception
+   */
+  public updateActiveFileReception(updates: Partial<ActiveFileReception>): void {
+    if (this.activeFileReception) {
+      Object.assign(this.activeFileReception, updates);
+    }
+  }
+
+  /**
+   * Complete active file reception
+   */
+  public completeFileReception(): void {
+    if (this.activeFileReception?.completionNotifier) {
+      this.activeFileReception.completionNotifier.resolve();
+    }
+    this.activeFileReception = null;
+  }
+
+  /**
+   * Fail active file reception
+   */
+  public failFileReception(reason: any): void {
+    if (this.activeFileReception?.completionNotifier) {
+      this.activeFileReception.completionNotifier.reject(reason);
+    }
+    this.activeFileReception = null;
+  }
+
+  // ===== String Reception Management =====
+
+  /**
+   * Start string reception
+   */
+  public startStringReception(length: number): void {
+    this.activeStringReception = {
+      length,
+      chunks: [],
+      receivedChunks: 0,
+    };
+  }
+
+  /**
+   * Get active string reception
+   */
+  public getActiveStringReception(): CurrentString | null {
+    return this.activeStringReception;
+  }
+
+  /**
+   * Update string reception chunk
+   */
+  public updateStringReceptionChunk(index: number, chunk: string): void {
+    if (this.activeStringReception) {
+      this.activeStringReception.chunks[index] = chunk;
+      this.activeStringReception.receivedChunks++;
+    }
+  }
+
+  /**
+   * Complete string reception
+   */
+  public completeStringReception(): string | null {
+    if (!this.activeStringReception) return null;
+    
+    const fullString = this.activeStringReception.chunks.join("");
+    this.activeStringReception = null;
+    return fullString;
+  }
+
+  // ===== Current Context Management =====
+
+  /**
+   * Set current folder name
+   */
+  public setCurrentFolderName(folderName: string | null): void {
+    this.currentFolderName = folderName;
+  }
+
+  /**
+   * Get current folder name
+   */
+  public getCurrentFolderName(): string | null {
+    return this.currentFolderName;
+  }
+
+  /**
+   * Set current peer ID
+   */
+  public setCurrentPeerId(peerId: string): void {
+    this.currentPeerId = peerId;
+  }
+
+  /**
+   * Get current peer ID
+   */
+  public getCurrentPeerId(): string {
+    return this.currentPeerId;
+  }
+
+  /**
+   * Set save directory
+   */
+  public setSaveDirectory(directory: FileSystemDirectoryHandle | null): void {
+    this.saveDirectory = directory;
+  }
+
+  /**
+   * Get save directory
+   */
+  public getSaveDirectory(): FileSystemDirectoryHandle | null {
+    return this.saveDirectory;
+  }
+
+  // ===== Save Type Management =====
+
+  /**
+   * Set save type for file or folder
+   */
+  public setSaveType(id: string, saveToDisk: boolean): void {
+    this.saveType[id] = saveToDisk;
+  }
+
+  /**
+   * Get save type for file or folder
+   */
+  public getSaveType(id: string): boolean {
+    return this.saveType[id] || false;
+  }
+
+  // ===== State Reset and Cleanup =====
+
+  /**
+   * Force reset all states (for reconnection scenarios)
+   */
+  public forceReset(): void {
+    this.pendingFilesMeta.clear();
+    this.folderProgresses = {};
+    this.saveType = {};
+    this.activeFileReception = null;
+    this.activeStringReception = null;
+    this.currentFolderName = null;
+    this.currentPeerId = "";
+    // Note: saveDirectory is preserved
+  }
+
+  /**
+   * Graceful cleanup (preserve some state for potential resume)
+   */
+  public gracefulCleanup(): void {
+    this.activeFileReception = null;
+    this.activeStringReception = null;
+    this.currentFolderName = null;
+    // Note: preserve pendingFilesMeta, folderProgresses, saveType for potential resume
+  }
+
+  /**
+   * Get state statistics (for debugging)
+   */
+  public getStateStats() {
+    return {
+      pendingFilesCount: this.pendingFilesMeta.size,
+      folderCount: Object.keys(this.folderProgresses).length,
+      hasActiveFileReception: !!this.activeFileReception,
+      hasActiveStringReception: !!this.activeStringReception,
+      currentFolderName: this.currentFolderName,
+      currentPeerId: this.currentPeerId,
+      hasSaveDirectory: !!this.saveDirectory,
+      saveTypeCount: Object.keys(this.saveType).length,
+    };
+  }
+}

frontend/lib/receive/StreamingFileWriter.ts

@@ -0,0 +1,430 @@
+import { ReceptionConfig } from "./ReceptionConfig";
+import { postLogToBackend } from "@/app/config/api";
+
+const developmentEnv = process.env.NODE_ENV;
+
+/**
+ * 🚀 Strict Sequential Buffering Writer - Optimizes large file disk I/O performance
+ */
+export class SequencedDiskWriter {
+  private writeQueue = new Map<number, ArrayBuffer>();
+  private nextWriteIndex = 0;
+  private readonly maxBufferSize: number;
+  private readonly stream: FileSystemWritableFileStream;
+  private totalWritten = 0;
+
+  constructor(stream: FileSystemWritableFileStream, startIndex: number = 0) {
+    this.stream = stream;
+    this.nextWriteIndex = startIndex;
+    this.maxBufferSize = ReceptionConfig.BUFFER_CONFIG.MAX_BUFFER_SIZE;
+  }
+
+  /**
+   * Write a chunk, automatically managing order and buffering
+   */
+  async writeChunk(chunkIndex: number, chunk: ArrayBuffer): Promise<void> {
+    // Debug writeChunk calls
+    if (
+      ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING &&
+      (chunkIndex <= 5 || chunkIndex === this.nextWriteIndex)
+    ) {
+      postLogToBackend(
+        `[DEBUG-RESUME] 🎯 WriteChunk called - received:${chunkIndex}, expected:${
+          this.nextWriteIndex
+        }, match:${chunkIndex === this.nextWriteIndex}`
+      );
+    }
+
+    // 1. If it is the expected next chunk, write immediately
+    if (chunkIndex === this.nextWriteIndex) {
+      await this.flushSequentialChunks(chunk);
+      return;
+    }
+
+    // 2. If it's a future chunk, buffer it
+    if (chunkIndex > this.nextWriteIndex) {
+      if (this.writeQueue.size < this.maxBufferSize) {
+        this.writeQueue.set(chunkIndex, chunk);
+      } else {
+        // Buffer full, forcing processing of the earliest chunk to free up space
+        await this.forceFlushOldest();
+        this.writeQueue.set(chunkIndex, chunk);
+      }
+      return;
+    }
+
+    // 3. If the chunk is expired, log a warning but ignore (already written)
+    if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] ⚠️ DUPLICATE chunk #${chunkIndex} ignored (already written #${this.nextWriteIndex})`
+      );
+    }
+  }
+
+  /**
+   * Write current chunk and attempt to sequentially write subsequent chunks
+   */
+  private async flushSequentialChunks(firstChunk: ArrayBuffer): Promise<void> {
+    let flushCount = 0;
+
+    try {
+      // Write current chunk
+      await this.stream.write(firstChunk);
+      this.totalWritten += firstChunk.byteLength;
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] ✓ DISK_WRITE chunk #${this.nextWriteIndex} - ${firstChunk.byteLength} bytes, total: ${this.totalWritten}`
+        );
+      }
+
+      this.nextWriteIndex++;
+
+      // Try to sequentially write chunks from buffer
+      while (this.writeQueue.has(this.nextWriteIndex)) {
+        const chunk = this.writeQueue.get(this.nextWriteIndex)!;
+        await this.stream.write(chunk);
+        this.totalWritten += chunk.byteLength;
+        this.writeQueue.delete(this.nextWriteIndex);
+
+        flushCount++;
+        this.nextWriteIndex++;
+      }
+    } catch (error) {
+      // Defensive handling: If stream is closed, silently ignore
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      if (
+        errorMessage.includes("closing writable stream") ||
+        errorMessage.includes("stream is closed")
+      ) {
+        console.log(
+          `[SequencedDiskWriter] Stream closed during write - ignoring remaining chunks`
+        );
+        return;
+      }
+      // Re-throw other types of errors
+      throw error;
+    }
+
+    if (flushCount > 0 && ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+      postLogToBackend(
+        `[DEBUG] 🔥 SEQUENTIAL_FLUSH ${flushCount} chunks, now at #${this.nextWriteIndex}, queue: ${this.writeQueue.size}`
+      );
+    }
+  }
+
+  /**
+   * Get the next expected write index
+   */
+  get expectedIndex(): number {
+    return this.nextWriteIndex;
+  }
+
+  /**
+   * Force flush the earliest chunk to release buffer space
+   */
+  private async forceFlushOldest(): Promise<void> {
+    try {
+      if (this.writeQueue.size === 0) return;
+
+      const oldestIndex = Math.min(...Array.from(this.writeQueue.keys()));
+      const chunk = this.writeQueue.get(oldestIndex)!;
+
+      // Use seek to write at the correct position (fallback handling)
+      const fileOffset = ReceptionConfig.getOffsetFromChunkIndex(oldestIndex);
+      await this.stream.seek(fileOffset);
+      await this.stream.write(chunk);
+      this.writeQueue.delete(oldestIndex);
+
+      // Return to current position
+      const currentOffset = ReceptionConfig.getOffsetFromChunkIndex(this.nextWriteIndex);
+      await this.stream.seek(currentOffset);
+    } catch (error) {
+      // Defensive handling: If stream is closed, silently ignore
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      if (
+        errorMessage.includes("closing writable stream") ||
+        errorMessage.includes("stream is closed")
+      ) {
+        console.log(
+          `[SequencedDiskWriter] Stream closed during write - ignoring remaining chunks`
+        );
+        return;
+      }
+      // Re-throw other types of errors
+      throw error;
+    }
+  }
+
+  /**
+   * Get buffer status
+   */
+  getBufferStatus(): {
+    queueSize: number;
+    nextIndex: number;
+    totalWritten: number;
+  } {
+    return {
+      queueSize: this.writeQueue.size,
+      nextIndex: this.nextWriteIndex,
+      totalWritten: this.totalWritten,
+    };
+  }
+
+  /**
+   * Close and clean up resources
+   */
+  async close(): Promise<void> {
+    try {
+      // 🔧 修复：确保以正确的WriteParams格式写入剩余chunks
+      const remainingIndexes = Array.from(this.writeQueue.keys()).sort(
+        (a, b) => a - b
+      );
+      
+      if (remainingIndexes.length > 0) {
+        if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+          postLogToBackend(
+            `[DEBUG-FINALIZE] 💾 Flushing ${remainingIndexes.length} remaining chunks: [${remainingIndexes.join(',')}]`
+          );
+        }
+        
+        for (const chunkIndex of remainingIndexes) {
+          const chunk = this.writeQueue.get(chunkIndex)!;
+          const fileOffset = ReceptionConfig.getOffsetFromChunkIndex(chunkIndex);
+          
+          // 🔧 修复：使用正确的WriteParams格式
+          await this.stream.seek(fileOffset);
+          
+          // 确保chunk是有效的ArrayBuffer
+          if (!(chunk instanceof ArrayBuffer) || chunk.byteLength === 0) {
+            if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+              postLogToBackend(
+                `[DEBUG-FINALIZE] ⚠️ Skipping invalid chunk #${chunkIndex}: ${Object.prototype.toString.call(chunk)}, size: ${chunk.byteLength}`
+              );
+            }
+            continue;
+          }
+          
+          // 使用标准WriteParams格式写入
+          await this.stream.write({
+            type: "write",
+            data: chunk
+          });
+          
+          if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+            postLogToBackend(
+              `[DEBUG-FINALIZE] ✅ FINAL_FLUSH chunk #${chunkIndex} (${chunk.byteLength} bytes)`
+            );
+          }
+        }
+      }
+    } catch (error) {
+      // Enhanced error handling with specific error types
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ❌ Error during final flush: ${errorMessage}`
+        );
+      }
+      
+      if (
+        errorMessage.includes("closing writable stream") ||
+        errorMessage.includes("stream is closed") ||
+        errorMessage.includes("The stream is not in a state that permits this operation")
+      ) {
+        console.log(
+          `[SequencedDiskWriter] Stream closed during final flush - completing gracefully`
+        );
+      } else {
+        console.warn(`[SequencedDiskWriter] Unexpected error during final flush:`, errorMessage);
+        throw error;
+      }
+    } finally {
+      // 无论如何都要清理队列
+      this.writeQueue.clear();
+    }
+  }
+}
+
+/**
+ * 🚀 Streaming file writer
+ * Manages disk file creation, directory structure, and streaming writes
+ */
+export class StreamingFileWriter {
+  private saveDirectory: FileSystemDirectoryHandle | null = null;
+
+  constructor(saveDirectory?: FileSystemDirectoryHandle) {
+    this.saveDirectory = saveDirectory || null;
+  }
+
+  /**
+   * Set save directory
+   */
+  setSaveDirectory(directory: FileSystemDirectoryHandle): void {
+    this.saveDirectory = directory;
+  }
+
+  /**
+   * Create disk write stream for a file
+   */
+  async createWriteStream(
+    fileName: string,
+    fullPath: string,
+    offset: number = 0
+  ): Promise<{
+    fileHandle: FileSystemFileHandle;
+    writeStream: FileSystemWritableFileStream;
+    sequencedWriter: SequencedDiskWriter;
+  }> {
+    if (!this.saveDirectory) {
+      throw new Error("Save directory not set");
+    }
+
+    try {
+      const folderHandle = await this.createFolderStructure(fullPath);
+      const fileHandle = await folderHandle.getFileHandle(fileName, {
+        create: true,
+      });
+
+      // Use keepExistingData: true to append
+      const writeStream = await fileHandle.createWritable({
+        keepExistingData: true,
+      });
+
+      // Seek to the offset to start writing from there
+      await writeStream.seek(offset);
+
+      // Create strictly sequential write manager
+      const startChunkIndex = ReceptionConfig.getChunkIndexFromOffset(offset);
+      const sequencedWriter = new SequencedDiskWriter(writeStream, startChunkIndex);
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG] 📢 SEQUENCED_WRITER created - startIndex: ${startChunkIndex}, offset: ${offset}`
+        );
+        postLogToBackend(
+          `[DEBUG-RESUME] 🎯 SequencedWriter expects - startIndex:${startChunkIndex}, offset:${offset}, calculatedFrom:${offset}/65536`
+        );
+      }
+
+      return { fileHandle, writeStream, sequencedWriter };
+    } catch (err) {
+      throw new Error(`Failed to create file on disk: ${err}`);
+    }
+  }
+
+  /**
+   * Check if partial file exists and get its size
+   */
+  async getPartialFileSize(fileName: string, fullPath: string): Promise<number> {
+    if (!this.saveDirectory) {
+      return 0;
+    }
+
+    try {
+      const folderHandle = await this.createFolderStructure(fullPath);
+      const fileHandle = await folderHandle.getFileHandle(fileName, {
+        create: false,
+      });
+      const file = await fileHandle.getFile();
+      return file.size;
+    } catch {
+      // File does not exist
+      return 0;
+    }
+  }
+
+  /**
+   * Create folder structure based on full path
+   */
+  private async createFolderStructure(
+    fullPath: string
+  ): Promise<FileSystemDirectoryHandle> {
+    if (!this.saveDirectory) {
+      throw new Error("Save directory not set");
+    }
+
+    const parts = fullPath.split("/");
+    parts.pop(); // Remove filename
+
+    let currentDir = this.saveDirectory;
+    for (const part of parts) {
+      if (part) {
+        currentDir = await currentDir.getDirectoryHandle(part, {
+          create: true,
+        });
+      }
+    }
+    return currentDir;
+  }
+
+  /**
+   * Finalize file write and close streams
+   */
+  async finalizeWrite(
+    sequencedWriter: SequencedDiskWriter,
+    writeStream: FileSystemWritableFileStream,
+    fileName: string
+  ): Promise<void> {
+    try {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] 🚀 Starting finalization for ${fileName}`
+        );
+      }
+
+      // First close the strict sequential writing manager (flush all buffers)
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(`[DEBUG-FINALIZE] Closing SequencedWriter...`);
+      }
+      await sequencedWriter.close();
+      const status = sequencedWriter.getBufferStatus();
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] 💾 SEQUENCED_WRITER closed - totalWritten: ${status.totalWritten}, finalQueue: ${status.queueSize}`
+        );
+      }
+
+      // Then close the file stream
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] About to close writeStream for ${fileName}`
+        );
+      }
+      await writeStream.close();
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(`[DEBUG-FINALIZE] ✅ WriteStream closed successfully`);
+      }
+
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ✅ LARGE_FILE finalized successfully - ${fileName}`
+        );
+      }
+    } catch (error) {
+      if (ReceptionConfig.DEBUG_CONFIG.ENABLE_CHUNK_LOGGING) {
+        postLogToBackend(
+          `[DEBUG-FINALIZE] ❌ Error during finalization: ${error}`
+        );
+      }
+      throw new Error(`Error finalizing large file: ${error}`);
+    }
+  }
+
+  /**
+   * Check if save directory is available
+   */
+  hasSaveDirectory(): boolean {
+    return !!this.saveDirectory;
+  }
+
+  /**
+   * Get save directory
+   */
+  getSaveDirectory(): FileSystemDirectoryHandle | null {
+    return this.saveDirectory;
+  }
+}

frontend/lib/receive/index.ts

@@ -0,0 +1,45 @@
+/**
+ * 🚀 File receive module unified export
+ * Provides modular file reception services
+ */
+
+// Configuration management
+export { ReceptionConfig } from "./ReceptionConfig";
+
+// State management
+export { ReceptionStateManager } from "./ReceptionStateManager";
+export type { ActiveFileReception } from "./ReceptionStateManager";
+
+// Data processing
+export { ChunkProcessor } from "./ChunkProcessor";
+export type { ChunkProcessingResult } from "./ChunkProcessor";
+
+// File writing
+export { StreamingFileWriter, SequencedDiskWriter } from "./StreamingFileWriter";
+
+// File assembly
+export { FileAssembler } from "./FileAssembler";
+export type { FileAssemblyResult } from "./FileAssembler";
+
+// Message processing
+export { MessageProcessor } from "./MessageProcessor";
+export type { MessageProcessorDelegate } from "./MessageProcessor";
+
+// Progress reporting
+export { ProgressReporter } from "./ProgressReporter";
+export type { ProgressCallback, ProgressStats } from "./ProgressReporter";
+
+// Main orchestrator
+export { FileReceiveOrchestrator } from "./FileReceiveOrchestrator";
+
+/**
+ * 🎯 Convenience creation function - Quick initialization of file receive services
+ */
+import WebRTC_Recipient from "../webrtc_Recipient";
+import { FileReceiveOrchestrator } from "./FileReceiveOrchestrator";
+
+export function createFileReceiveService(
+  webrtcConnection: WebRTC_Recipient
+): FileReceiveOrchestrator {
+  return new FileReceiveOrchestrator(webrtcConnection);
+}

frontend/lib/tracking.ts

@@ -4,7 +4,7 @@ export const trackReferrer = async () => {
   // Get URL parameters
   const urlParams = new URLSearchParams(window.location.search);
   let ref = urlParams.get("ref");
-  if (process.env.NEXT_PUBLIC_development === "false") {
+  if (process.env.NODE_ENV === "production") {
     ref = urlParams.get("ref") || "noRef"; // Production environment, count daily active users, record as noRef if there is no ref
   }
 

frontend/lib/transfer/FileTransferOrchestrator.ts

@@ -0,0 +1,463 @@
+import { generateFileId } from "@/lib/fileUtils";
+import {
+  CustomFile,
+  fileMetadata,
+  WebRTCMessage,
+  FileRequest,
+  EmbeddedChunkMeta,
+} from "@/types/webrtc";
+import { StateManager } from "./StateManager";
+import { MessageHandler, MessageHandlerDelegate } from "./MessageHandler";
+import { NetworkTransmitter } from "./NetworkTransmitter";
+import { ProgressTracker, ProgressCallback } from "./ProgressTracker";
+import { StreamingFileReader } from "./StreamingFileReader";
+import { TransferConfig } from "./TransferConfig";
+import WebRTC_Initiator from "../webrtc_Initiator";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
+/**
+ * 🚀 File transfer orchestrator
+ * Integrates all components to provide unified file transfer services
+ */
+export class FileTransferOrchestrator implements MessageHandlerDelegate {
+  private stateManager: StateManager;
+  private messageHandler: MessageHandler;
+  private networkTransmitter: NetworkTransmitter;
+  private progressTracker: ProgressTracker;
+
+  constructor(private webrtcConnection: WebRTC_Initiator) {
+    // Initialize all components
+    this.stateManager = new StateManager();
+    this.networkTransmitter = new NetworkTransmitter(
+      webrtcConnection,
+      this.stateManager
+    );
+    this.progressTracker = new ProgressTracker(this.stateManager);
+    this.messageHandler = new MessageHandler(this.stateManager, this);
+
+    // Set up data handler
+    this.setupDataHandler();
+
+    this.log("log", "FileTransferOrchestrator initialized");
+  }
+  /**
+   * 🎯 Send file metadata
+   */
+  public sendFileMeta(files: CustomFile[], peerId?: string): void {
+    // Record file sizes belonging to folders for progress calculation
+    files.forEach((file) => {
+      if (file.folderName) {
+        const fileId = generateFileId(file);
+        this.stateManager.addFileToFolder(file.folderName, fileId, file.size);
+      }
+    });
+
+    // Loop to send metadata for all files
+    const peers = peerId
+      ? [peerId]
+      : Array.from(this.webrtcConnection.peerConnections.keys());
+
+    peers.forEach((pId) => {
+      files.forEach((file) => {
+        const fileId = generateFileId(file);
+        this.stateManager.addPendingFile(fileId, file);
+
+        const fileMeta = this.getFileMeta(file);
+        const metaDataString = JSON.stringify(fileMeta);
+
+        const sendResult = this.webrtcConnection.sendData(metaDataString, pId);
+        if (!sendResult) {
+          this.fireError("Failed to send file metadata", {
+            fileMeta,
+            peerId: pId,
+          });
+        }
+      });
+    });
+  }
+
+  /**
+   * 🎯 Send string content
+   */
+  public async sendString(content: string, peerId: string): Promise<void> {
+    const chunkSize = TransferConfig.FILE_CONFIG.CHUNK_SIZE;
+    const chunks: string[] = [];
+
+    for (let i = 0; i < content.length; i += chunkSize) {
+      chunks.push(content.slice(i, i + chunkSize));
+    }
+
+    // First send metadata
+    await this.networkTransmitter.sendWithBackpressure(
+      JSON.stringify({
+        type: "stringMetadata",
+        length: content.length,
+      }),
+      peerId
+    );
+
+    // Send chunks one by one using backpressure control
+    for (let i = 0; i < chunks.length; i++) {
+      const data = JSON.stringify({
+        type: "string",
+        chunk: chunks[i],
+        index: i,
+        total: chunks.length,
+      });
+      await this.networkTransmitter.sendWithBackpressure(data, peerId);
+    }
+
+    this.log(
+      "log",
+      `String sent successfully - length: ${content.length}, chunks: ${chunks.length}`,
+      { peerId }
+    );
+  }
+
+  /**
+   * 🎯 Set progress callback
+   */
+  public setProgressCallback(callback: ProgressCallback, peerId: string): void {
+    this.progressTracker.setProgressCallback(callback, peerId);
+  }
+
+  // ===== MessageHandlerDelegate Implementation =====
+
+  /**
+   * 📄 Handle file request (delegated from MessageHandler)
+   */
+  async handleFileRequest(request: FileRequest, peerId: string): Promise<void> {
+    const file = this.stateManager.getPendingFile(request.fileId);
+    const offset = request.offset || 0;
+
+    if (!file) {
+      this.fireError(`File not found for request`, {
+        fileId: request.fileId,
+        peerId,
+      });
+      return;
+    }
+
+    await this.sendSingleFile(file, peerId, offset);
+  }
+
+  /**
+   * 📝 Logging (delegated from MessageHandler)
+   */
+  public log(
+    level: "log" | "warn" | "error",
+    message: string,
+    context?: Record<string, any>
+  ): void {
+    const prefix = `[FileTransferOrchestrator]`;
+    console[level](prefix, message, context || "");
+  }
+
+  // ===== Internal Orchestration Methods =====
+
+  /**
+   * 🎯 Send single file
+   */
+  private async sendSingleFile(
+    file: CustomFile,
+    peerId: string,
+    offset: number = 0
+  ): Promise<void> {
+    const fileId = generateFileId(file);
+    const peerState = this.stateManager.getPeerState(peerId);
+    if (peerState.isSending) {
+      this.log("warn", `Already sending file to peer ${peerId}`, { fileId });
+      return;
+    }
+
+    // Initialize sending state
+    this.stateManager.updatePeerState(peerId, {
+      isSending: true,
+      currentFolderName: file.folderName,
+      readOffset: offset,
+      bufferQueue: [],
+      isReading: false,
+    });
+    // Initialize progress statistics
+    const currentSent = this.stateManager.getFileBytesSent(peerId, fileId);
+    this.stateManager.updateFileBytesSent(peerId, fileId, offset - currentSent);
+
+    try {
+      await this.processSendQueue(file, peerId);
+      await this.waitForTransferComplete(peerId);
+    } catch (error: any) {
+      this.fireError(`Error sending file ${file.name}: ${error.message}`, {
+        fileId,
+        peerId,
+      });
+      this.abortFileSend(fileId, peerId);
+    }
+  }
+
+  /**
+   * 🚀 Process send queue - Using StreamingFileReader
+   */
+  private async processSendQueue(
+    file: CustomFile,
+    peerId: string
+  ): Promise<void> {
+    const fileId = generateFileId(file);
+    const peerState = this.stateManager.getPeerState(peerId);
+    const transferStartTime = performance.now();
+
+    // 🔧 Fix: Record initial offset at the start of transmission, used for subsequent statistics calculation
+    const initialReadOffset = peerState.readOffset || 0;
+
+    // 1. Initialize streaming file reader
+    const streamReader = new StreamingFileReader(file, initialReadOffset);
+
+    if (developmentEnv === "development") {
+      postLogToBackend(
+        `[DEBUG] 🚀 Starting transfer - file: ${file.name}, size: ${(
+          file.size /
+          1024 /
+          1024
+        ).toFixed(1)}MB`
+      );
+    }
+
+    try {
+      let totalBytesSent = 0;
+      let networkChunkIndex = 0;
+      let totalReadTime = 0;
+      let totalSendTime = 0;
+      let totalProgressTime = 0;
+      let lastProgressTime = performance.now();
+
+      // 2. Stream processing: Get 64KB network chunks one by one and send
+      while (peerState.isSending) {
+        // Get next network chunk
+        const readStartTime = performance.now();
+        const chunkInfo = await streamReader.getNextNetworkChunk();
+        const readTime = performance.now() - readStartTime;
+        totalReadTime += readTime;
+
+        // Check if completed
+        if (chunkInfo.chunk === null) {
+          break;
+        }
+
+        // Build embedded metadata
+        const embeddedMeta: EmbeddedChunkMeta = {
+          chunkIndex: chunkInfo.chunkIndex,
+          totalChunks: chunkInfo.totalChunks,
+          chunkSize: chunkInfo.chunk.byteLength,
+          isLastChunk: chunkInfo.isLastChunk,
+          fileOffset: chunkInfo.fileOffset,
+          fileId,
+        };
+
+        // Send network chunk with embedded metadata
+        let sendSuccessful = false;
+        const sendStartTime = performance.now();
+        try {
+          sendSuccessful = await this.networkTransmitter.sendEmbeddedChunk(
+            chunkInfo.chunk,
+            embeddedMeta,
+            peerId
+          );
+
+          if (sendSuccessful) {
+            totalBytesSent += chunkInfo.chunk.byteLength;
+          }
+        } catch (error) {
+          this.log(
+            "warn",
+            `Chunk send failed #${chunkInfo.chunkIndex}: ${error}`
+          );
+          sendSuccessful = false;
+        }
+        const sendTime = performance.now() - sendStartTime;
+        totalSendTime += sendTime;
+
+        // Update state and progress
+        if (sendSuccessful) {
+          this.stateManager.updatePeerState(peerId, {
+            readOffset: chunkInfo.fileOffset + chunkInfo.chunk.byteLength,
+          });
+
+          const progressStartTime = performance.now();
+          await this.progressTracker.updateFileProgress(
+            chunkInfo.chunk.byteLength,
+            fileId,
+            file.size,
+            peerId,
+            true
+          );
+          const progressTime = performance.now() - progressStartTime;
+          totalProgressTime += progressTime;
+        }
+
+        networkChunkIndex++;
+
+        // Check if it's the last chunk
+        if (chunkInfo.isLastChunk) {
+          break;
+        }
+      }
+
+      if (developmentEnv === "development") {
+        const totalTime = performance.now() - transferStartTime;
+        const avgSpeedMBps = totalBytesSent / 1024 / 1024 / (totalTime / 1000);
+
+        // 🔧 Fix: Use correct initial offset instead of current readOffset for log statistics
+        const initialOffset = initialReadOffset || 0; // Initial offset at the start of transmission
+        const expectedTotalChunks = Math.ceil(file.size / 65536);
+        const startChunkIndex = Math.floor(initialOffset / 65536);
+        const expectedChunksSent = expectedTotalChunks - startChunkIndex;
+
+        postLogToBackend(
+          `[DEBUG-CHUNKS] ✅ Transfer complete - file: ${file.name}, time: ${(
+            totalTime / 1000
+          ).toFixed(1)}s, speed: ${avgSpeedMBps.toFixed(1)}MB/s`
+        );
+        postLogToBackend(
+          `[DEBUG-CHUNKS] Chunks sent: ${networkChunkIndex}, expected: ${expectedChunksSent}, startChunk: ${startChunkIndex}, totalFileChunks: ${expectedTotalChunks}, initialOffset: ${initialOffset}`
+        );
+
+        if (networkChunkIndex !== expectedChunksSent) {
+          postLogToBackend(
+            `[DEBUG-CHUNKS] ⚠️ CHUNK MISMATCH: sent ${networkChunkIndex} but expected ${expectedChunksSent}`
+          );
+        }
+      }
+    } catch (error: any) {
+      const errorMessage = `Streaming send error: ${error.message}`;
+      if (developmentEnv === "development") {
+        postLogToBackend(`[DEBUG] ❌ Transfer error: ${errorMessage}`);
+      }
+      this.fireError(errorMessage, {
+        fileId,
+        peerId,
+        offset: peerState.readOffset,
+      });
+      throw error;
+    } finally {
+      // Clean up resources
+      streamReader.cleanup();
+    }
+  }
+
+  /**
+   * ⏳ Wait for transfer completion confirmation
+   */
+  private async waitForTransferComplete(peerId: string): Promise<void> {
+    while (true) {
+      const currentPeerState = this.stateManager.getPeerState(peerId);
+
+      // Check if it has been cleaned up or does not exist
+      if (!currentPeerState || !currentPeerState.isSending) {
+        this.log("log", `Transfer completed or peer disconnected: ${peerId}`);
+        break;
+      }
+
+      // Check if the WebRTC connection is still valid
+      if (!this.webrtcConnection.peerConnections.has(peerId)) {
+        this.log("log", `Peer connection lost: ${peerId}, stopping transfer`);
+        this.stateManager.updatePeerState(peerId, { isSending: false });
+        break;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  /**
+   * 📋 Get file metadata
+   */
+  private getFileMeta(file: CustomFile): fileMetadata {
+    const fileId = generateFileId(file);
+    return {
+      type: "fileMeta",
+      fileId,
+      name: file.name,
+      size: file.size,
+      fileType: file.type,
+      fullName: file.fullName,
+      folderName: file.folderName,
+    };
+  }
+
+  /**
+   * ❌ Abort file sending
+   */
+  private abortFileSend(fileId: string, peerId: string): void {
+    this.log("warn", `Aborting file send for ${fileId} to ${peerId}`);
+    this.stateManager.resetPeerState(peerId);
+  }
+
+  /**
+   * 🔧 Set up data handler
+   */
+  private setupDataHandler(): void {
+    this.webrtcConnection.onDataReceived = (data, peerId) => {
+      if (typeof data === "string") {
+        try {
+          const parsedData = JSON.parse(data) as WebRTCMessage;
+          this.messageHandler.handleSignalingMessage(parsedData, peerId);
+        } catch (error) {
+          this.fireError("Error parsing received JSON data", { error, peerId });
+        }
+      }
+    };
+  }
+
+  /**
+   * 🔥 Error handling
+   */
+  private fireError(message: string, context?: Record<string, any>) {
+    this.webrtcConnection.fireError(message, {
+      ...context,
+      component: "FileTransferOrchestrator",
+    });
+  }
+
+  // ===== State Query and Debugging =====
+
+  /**
+   * 📊 Get transfer statistics
+   */
+  public getTransferStats(peerId?: string) {
+    const stats = {
+      stateManager: this.stateManager.getStateStats(),
+      progressTracker: peerId
+        ? this.progressTracker.getProgressStats(peerId)
+        : null,
+      networkTransmitter: peerId
+        ? this.networkTransmitter.getTransmissionStats(peerId)
+        : null,
+    };
+
+    return stats;
+  }
+
+  /**
+   * 🔄 Handle peer reconnection
+   */
+  public handlePeerReconnection(peerId: string): void {
+    // Clear all transfer states for this peer
+    this.stateManager.clearPeerState(peerId);
+    if (developmentEnv === "development")
+      this.log(
+        "log",
+        `Successfully reset transfer state for reconnected peer ${peerId}`
+      );
+  }
+
+  /**
+   * 🧹 Clean up all resources
+   */
+  public cleanup(): void {
+    this.stateManager.cleanup();
+    this.networkTransmitter.cleanup();
+    this.progressTracker.cleanup();
+    this.messageHandler.cleanup();
+    if (developmentEnv === "development")
+      this.log("log", "FileTransferOrchestrator cleaned up");
+  }
+}

frontend/lib/transfer/MessageHandler.ts

@@ -0,0 +1,178 @@
+import {
+  WebRTCMessage,
+  FileRequest,
+  FileReceiveComplete,
+  FolderReceiveComplete
+} from "@/types/webrtc";
+import { StateManager } from "./StateManager";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
+/**
+ * 🚀 Message handling interface - Communicate with main orchestrator
+ */
+export interface MessageHandlerDelegate {
+  handleFileRequest(request: FileRequest, peerId: string): Promise<void>;
+  log(
+    level: "log" | "warn" | "error",
+    message: string,
+    context?: Record<string, any>
+  ): void;
+}
+
+/**
+ * 🚀 Message handler
+ * Responsible for WebRTC message routing and processing logic
+ */
+export class MessageHandler {
+  constructor(
+    private stateManager: StateManager,
+    private delegate: MessageHandlerDelegate
+  ) {}
+
+  /**
+   * 🎯 Handle received signaling message
+   */
+  handleSignalingMessage(message: WebRTCMessage, peerId: string): void {
+    // Delete frequent message reception logs
+
+    switch (message.type) {
+      case "fileRequest":
+        this.handleFileRequest(message as FileRequest, peerId);
+        break;
+      case "fileReceiveComplete":
+        this.handleFileReceiveComplete(message as FileReceiveComplete, peerId);
+        break;
+      case "folderReceiveComplete":
+        this.handleFolderReceiveComplete(
+          message as FolderReceiveComplete,
+          peerId
+        );
+        break;
+      default:
+        this.delegate.log("warn", `Unknown signaling message type received`, {
+          type: message.type,
+          peerId,
+        });
+    }
+  }
+
+  /**
+   * 📄 Handle file request message
+   */
+  private async handleFileRequest(
+    request: FileRequest,
+    peerId: string
+  ): Promise<void> {
+    const offset = request.offset || 0;
+
+    this.delegate.log(
+      "log",
+      `Handling file request for ${request.fileId} from ${peerId} with offset ${offset}`
+    );
+
+    // Firefox compatibility fix: Add slightly longer delay to ensure receiver is fully ready
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Delegate to main orchestrator for specific file transfer
+    try {
+      await this.delegate.handleFileRequest(request, peerId);
+    } catch (error) {
+      this.delegate.log("error", `Error handling file request`, {
+        fileId: request.fileId,
+        peerId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * ✅ Handle file receive completion confirmation message
+   */
+  private handleFileReceiveComplete(
+    message: FileReceiveComplete,
+    peerId: string
+  ): void {
+    // Clean up sending state
+    this.stateManager.updatePeerState(peerId, { isSending: false });
+
+    // Get peer state to trigger progress callback
+    const peerState = this.stateManager.getPeerState(peerId);
+
+    // Trigger single file 100% progress (only for non-folder cases)
+    if (!peerState.currentFolderName) {
+      // Delete frequent progress logs
+      peerState.progressCallback?.(message.fileId, 1, 0);
+    } else {
+      // Delete frequent folder progress logs
+    }
+
+    this.delegate.log("log", `File reception confirmed by peer ${peerId}`, {
+      fileId: message.fileId,
+      receivedSize: message.receivedSize,
+      storeUpdated: message.storeUpdated,
+    });
+  }
+
+  /**
+   * 📁 Handle folder receive completion confirmation message
+   */
+  private handleFolderReceiveComplete(
+    message: FolderReceiveComplete,
+    peerId: string
+  ): void {
+    if (developmentEnv === "development") {
+      postLogToBackend(
+        `[DEBUG] 📥 Folder complete - folderName: ${message.folderName}, files: ${message.completedFileIds.length}`
+      );
+    }
+
+    // Get peer state to trigger progress callback
+    const peerState = this.stateManager.getPeerState(peerId);
+
+    // Trigger folder 100% progress
+    const folderMeta = this.stateManager.getFolderMeta(message.folderName);
+    if (folderMeta) {
+      postLogToBackend(
+        `[DEBUG] 🎯 Setting folder progress to 100% - ${message.folderName}`
+      );
+      peerState.progressCallback?.(message.folderName, 1, 0);
+    } else {
+      this.delegate.log(
+        "warn",
+        `Folder metadata not found for completed folder`,
+        {
+          folderName: message.folderName,
+          peerId,
+        }
+      );
+    }
+
+    this.delegate.log("log", `Folder reception confirmed by peer ${peerId}`, {
+      folderName: message.folderName,
+      completedFiles: message.completedFileIds.length,
+      allStoreUpdated: message.allStoreUpdated,
+    });
+  }
+
+  /**
+   * 📊 Get message handling statistics
+   */
+  public getMessageStats(): {
+    handledMessages: number;
+    lastMessageTime: number | null;
+  } {
+    // Message statistics logic can be added here if needed
+    return {
+      handledMessages: 0, // TODO: Implement message counting
+      lastMessageTime: null, // TODO: Record last message time
+    };
+  }
+
+  /**
+   * 🧹 Clean up resources
+   */
+  public cleanup(): void {
+    if (developmentEnv === "development")
+      postLogToBackend("[DEBUG] 🧹 MessageHandler cleaned up");
+  }
+}

frontend/lib/transfer/NetworkTransmitter.ts

@@ -0,0 +1,246 @@
+import { EmbeddedChunkMeta } from "@/types/webrtc";
+import { StateManager } from "./StateManager";
+import WebRTC_Initiator from "../webrtc_Initiator";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
+/**
+ * 🚀 Network transmitter - Simplified version
+ * Uses WebRTC native bufferedAmountLowThreshold for backpressure control
+ */
+export class NetworkTransmitter {
+  constructor(
+    private webrtcConnection: WebRTC_Initiator,
+    private stateManager: StateManager
+  ) {}
+
+  /**
+   * 🎯 Send embedded chunk packet with sequence number
+   */
+  async sendEmbeddedChunk(
+    chunkData: ArrayBuffer,
+    metadata: EmbeddedChunkMeta,
+    peerId: string
+  ): Promise<boolean> {
+    try {
+      // 1. Build fused data packet
+      const embeddedPacket = this.createEmbeddedChunkPacket(
+        chunkData,
+        metadata
+      );
+
+      // 2. Send complete fused data packet (no fragmentation)
+      await this.sendSingleData(embeddedPacket, peerId);
+
+      // Key node logs (development environment only)
+
+      // if (
+      //   developmentEnv === "development" &&
+      //   (metadata.chunkIndex % 100 === 0 || metadata.isLastChunk)
+      // ) {
+      //   postLogToBackend(
+      //     `[DEBUG] ✓ CHUNK #${metadata.chunkIndex}/${
+      //       metadata.totalChunks
+      //     } sent, size: ${(chunkData.byteLength / 1024).toFixed(
+      //       1
+      //     )}KB, isLast: ${metadata.isLastChunk}`
+      //   );
+      // }
+
+      return true;
+    } catch (error) {
+      if (developmentEnv === "development") {
+        postLogToBackend(
+          `[DEBUG] ❌ CHUNK #${metadata.chunkIndex} send failed: ${error}`
+        );
+      }
+      return false;
+    }
+  }
+
+  /**
+   * 🚀 Build data packet with embedded metadata
+   */
+  private createEmbeddedChunkPacket(
+    chunkData: ArrayBuffer,
+    chunkMeta: EmbeddedChunkMeta
+  ): ArrayBuffer {
+    // 1. Serialize metadata to JSON
+    const metaJson = JSON.stringify(chunkMeta);
+    const metaBytes = new TextEncoder().encode(metaJson);
+
+    // 2. Metadata length (4 bytes)
+    const metaLengthBuffer = new ArrayBuffer(4);
+    const metaLengthView = new Uint32Array(metaLengthBuffer);
+    metaLengthView[0] = metaBytes.length;
+
+    // 3. Build final fused packet
+    const totalLength = 4 + metaBytes.length + chunkData.byteLength;
+    const finalPacket = new Uint8Array(totalLength);
+
+    // Concatenate: [4-byte length] + [metadata] + [original chunk data]
+    finalPacket.set(new Uint8Array(metaLengthBuffer), 0);
+    finalPacket.set(metaBytes, 4);
+    finalPacket.set(new Uint8Array(chunkData), 4 + metaBytes.length);
+
+    return finalPacket.buffer;
+  }
+
+  /**
+   * 🚀 Send single data packet (no fragmentation)
+   */
+  private async sendSingleData(
+    data: string | ArrayBuffer,
+    peerId: string
+  ): Promise<void> {
+    const dataChannel = this.webrtcConnection.dataChannels.get(peerId);
+    if (!dataChannel) {
+      throw new Error("Data channel not found");
+    }
+
+    // Simplified backpressure control
+    await this.simpleBufferControl(dataChannel, peerId);
+
+    // Send directly, no fragmentation
+    const sendResult = this.webrtcConnection.sendData(data, peerId);
+
+    if (!sendResult) {
+      const errorMessage = `sendData failed`;
+
+      if (developmentEnv === "development") {
+        postLogToBackend(`[DEBUG] ❌ ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * 🎯 Native backpressure control - Using WebRTC standard mechanism
+   */
+  private async simpleBufferControl(
+    dataChannel: RTCDataChannel,
+    peerId: string
+  ): Promise<void> {
+    const maxBuffer = 3 * 1024 * 1024; // 3MB maximum buffer
+    const lowThreshold = 512 * 1024; // 512KB low threshold
+
+    // Set native low threshold
+    if (dataChannel.bufferedAmountLowThreshold !== lowThreshold) {
+      dataChannel.bufferedAmountLowThreshold = lowThreshold;
+    }
+
+    // If buffer exceeds maximum, wait until it drops to low threshold
+    if (dataChannel.bufferedAmount > maxBuffer) {
+      const startTime = performance.now();
+      const initialBuffered = dataChannel.bufferedAmount;
+
+      await new Promise<void>((resolve) => {
+        const onLow = () => {
+          dataChannel.removeEventListener("bufferedamountlow", onLow);
+          resolve();
+        };
+        dataChannel.addEventListener("bufferedamountlow", onLow);
+
+        // Add timeout protection to avoid infinite waiting
+        setTimeout(() => {
+          dataChannel.removeEventListener("bufferedamountlow", onLow);
+          resolve();
+        }, 5000); // 5 second timeout
+      });
+
+      // Only output backpressure logs in development environment
+      // if (developmentEnv === "development") {
+      //   const waitTime = performance.now() - startTime;
+      //   postLogToBackend(
+      //     `[DEBUG] 🚀 BACKPRESSURE - wait: ${waitTime.toFixed(
+      //       1
+      //     )}ms, buffered: ${(initialBuffered / 1024).toFixed(0)}KB -> ${(
+      //       dataChannel.bufferedAmount / 1024
+      //     ).toFixed(0)}KB`
+      //   );
+      // }
+    }
+  }
+
+  /**
+   * 🚀 Send data with backpressure control
+   */
+  async sendWithBackpressure(
+    data: string | ArrayBuffer,
+    peerId: string
+  ): Promise<void> {
+    const dataChannel = this.webrtcConnection.dataChannels.get(peerId);
+    if (!dataChannel) {
+      throw new Error("Data channel not found");
+    }
+
+    try {
+      // For ArrayBuffer, if larger than 64KB, needs to be fragmented (fix sendData failed)
+      if (data instanceof ArrayBuffer) {
+        await this.sendLargeArrayBuffer(data, peerId);
+      } else {
+        await this.sendSingleData(data, peerId);
+      }
+    } catch (error) {
+      const errorMessage = `sendWithBackpressure failed: ${error}`;
+      if (developmentEnv === "development") {
+        postLogToBackend(`[DEBUG] ❌ ${errorMessage}`);
+      }
+      throw new Error(errorMessage);
+    }
+  }
+
+  /**
+   * 🚀 Send large ArrayBuffer (fragmentation processing)
+   */
+  private async sendLargeArrayBuffer(
+    data: ArrayBuffer,
+    peerId: string
+  ): Promise<void> {
+    const networkChunkSize = 65536; // 64KB
+    const totalSize = data.byteLength;
+
+    // If data is less than 64KB, send directly
+    if (totalSize <= networkChunkSize) {
+      await this.sendSingleData(data, peerId);
+      return;
+    }
+
+    // Fragment large data for sending
+    let offset = 0;
+    let fragmentIndex = 0;
+
+    while (offset < totalSize) {
+      const chunkSize = Math.min(networkChunkSize, totalSize - offset);
+      const chunk = data.slice(offset, offset + chunkSize);
+
+      // Send fragment
+      await this.sendSingleData(chunk, peerId);
+
+      offset += chunkSize;
+      fragmentIndex++;
+    }
+  }
+
+  /**
+   * 📊 Get transmission statistics
+   */
+  public getTransmissionStats(peerId: string) {
+    const dataChannel = this.webrtcConnection.dataChannels.get(peerId);
+
+    return {
+      peerId,
+      currentBufferedAmount: dataChannel?.bufferedAmount || 0,
+      bufferedAmountLowThreshold: dataChannel?.bufferedAmountLowThreshold || 0,
+      channelState: dataChannel?.readyState || "unknown",
+    };
+  }
+
+  /**
+   * 🧹 Clean up resources
+   */
+  public cleanup(): void {
+    if (developmentEnv === "development") {
+      postLogToBackend("[DEBUG] 🧹 NetworkTransmitter cleaned up");
+    }
+  }
+}

frontend/lib/transfer/ProgressTracker.ts

@@ -0,0 +1,231 @@
+import { SpeedCalculator } from "@/lib/speedCalculator";
+import { StateManager } from "./StateManager";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
+/**
+ * 🚀 Progress callback type definition
+ */
+export type ProgressCallback = (
+  fileId: string,
+  progress: number,
+  speed: number
+) => void;
+
+/**
+ * 🚀 Progress tracker
+ * Responsible for file and folder progress calculation, speed statistics, and callback triggering
+ */
+export class ProgressTracker {
+  private speedCalculator = new SpeedCalculator();
+
+  constructor(private stateManager: StateManager) {}
+
+  /**
+   * 🎯 Update file transfer progress
+   */
+  async updateFileProgress(
+    byteLength: number,
+    fileId: string,
+    fileSize: number,
+    peerId: string,
+    wasActuallySent: boolean = true
+  ): Promise<void> {
+    const peerState = this.stateManager.getPeerState(peerId);
+    if (!peerState) return;
+
+    // Important fix: Only update statistics for successfully sent data
+    if (!wasActuallySent) {
+      return;
+    }
+
+    // Update file sent bytes
+    this.stateManager.updateFileBytesSent(peerId, fileId, byteLength);
+
+    // Calculate progress ID and statistics
+    let progressFileId = fileId;
+    let currentBytes = this.stateManager.getFileBytesSent(peerId, fileId);
+    let totalSize = fileSize;
+
+    // If file belongs to a folder, recalculate folder progress
+    if (peerState.currentFolderName) {
+      const folderName = peerState.currentFolderName;
+      const folderMeta = this.stateManager.getFolderMeta(folderName);
+
+      progressFileId = folderName;
+      totalSize = folderMeta?.totalSize || 0;
+
+      // Recalculate folder progress (sum of progress from all its files)
+      // This is more robust and correct for resume downloads
+      currentBytes = this.stateManager.getFolderBytesSent(peerId, folderName);
+
+      // Delete frequent folder progress logs
+    }
+
+    // Update speed calculator
+    this.speedCalculator.updateSendSpeed(peerId, currentBytes);
+    const speed = this.speedCalculator.getSendSpeed(peerId);
+    const progress = totalSize > 0 ? currentBytes / totalSize : 0;
+
+    // Trigger progress callback
+    this.triggerProgressCallback(peerId, progressFileId, progress, speed);
+  }
+
+  /**
+   * 🎯 Update folder transfer progress
+   */
+  async updateFolderProgress(
+    folderName: string,
+    fileProgress: Record<string, number>,
+    peerId: string
+  ): Promise<void> {
+    const folderMeta = this.stateManager.getFolderMeta(folderName);
+    if (!folderMeta) {
+      postLogToBackend(`[DEBUG] ⚠️ Folder metadata not found: ${folderName}`);
+      return;
+    }
+
+    // Calculate total folder progress
+    let totalSentBytes = 0;
+    folderMeta.fileIds.forEach((fileId) => {
+      totalSentBytes += this.stateManager.getFileBytesSent(peerId, fileId);
+    });
+
+    const progress =
+      folderMeta.totalSize > 0 ? totalSentBytes / folderMeta.totalSize : 0;
+    const speed = this.speedCalculator.getSendSpeed(peerId);
+
+    // Trigger folder progress callback
+    this.triggerProgressCallback(peerId, folderName, progress, speed);
+
+    postLogToBackend(
+      `[DEBUG] 📁 Folder progress - ${folderName}: ${(progress * 100).toFixed(
+        2
+      )}%, speed: ${speed.toFixed(2)} KB/s, bytes: ${totalSentBytes}/${
+        folderMeta.totalSize
+      }`
+    );
+  }
+
+  /**
+   * 🎯 Set progress callback function
+   */
+  setProgressCallback(callback: ProgressCallback, peerId: string): void {
+    this.stateManager.updatePeerState(peerId, { progressCallback: callback });
+  }
+
+  /**
+   * 🎯 Trigger progress callback
+   */
+  private triggerProgressCallback(
+    peerId: string,
+    fileId: string,
+    progress: number,
+    speed: number
+  ): void {
+    const peerState = this.stateManager.getPeerState(peerId);
+    if (peerState.progressCallback) {
+      try {
+        peerState.progressCallback(fileId, progress, speed);
+      } catch (error) {
+        postLogToBackend(
+          `[DEBUG] ❌ Progress callback error - fileId: ${fileId}, error: ${error}`
+        );
+      }
+    }
+  }
+
+  /**
+   * 🎯 Calculate current transfer speed
+   */
+  getCurrentSpeed(peerId: string): number {
+    return this.speedCalculator.getSendSpeed(peerId);
+  }
+
+  /**
+   * 🎯 Complete file transfer progress (set to 100%)
+   */
+  completeFileProgress(fileId: string, peerId: string): void {
+    this.triggerProgressCallback(peerId, fileId, 1.0, 0);
+
+    postLogToBackend(`[DEBUG] ✅ File progress completed: ${fileId}`);
+  }
+
+  /**
+   * 🎯 Complete folder transfer progress (set to 100%)
+   */
+  completeFolderProgress(folderName: string, peerId: string): void {
+    this.triggerProgressCallback(peerId, folderName, 1.0, 0);
+
+    postLogToBackend(`[DEBUG] ✅ Folder progress completed: ${folderName}`);
+  }
+
+  /**
+   * 📊 Get detailed progress statistics
+   */
+  getProgressStats(peerId: string) {
+    const peerState = this.stateManager.getPeerState(peerId);
+    const currentSpeed = this.getCurrentSpeed(peerId);
+
+    // Calculate total sent bytes
+    let totalBytesSent = 0;
+    Object.values(peerState.totalBytesSent).forEach((bytes) => {
+      totalBytesSent += bytes;
+    });
+
+    return {
+      peerId,
+      currentSpeed,
+      totalBytesSent,
+      activeTransfers: Object.keys(peerState.totalBytesSent).length,
+      currentFolderName: peerState.currentFolderName,
+      isSending: peerState.isSending,
+      hasProgressCallback: !!peerState.progressCallback,
+    };
+  }
+
+  /**
+   * 📊 Get detailed folder progress information
+   */
+  getFolderProgressDetails(folderName: string, peerId: string) {
+    const folderMeta = this.stateManager.getFolderMeta(folderName);
+    if (!folderMeta) return null;
+
+    const fileProgresses: Record<
+      string,
+      { sent: number; total: number; progress: number }
+    > = {};
+    let totalSent = 0;
+
+    folderMeta.fileIds.forEach((fileId) => {
+      const sent = this.stateManager.getFileBytesSent(peerId, fileId);
+      // Note: Need to get file size from pendingFiles, temporarily using 0
+      const total = 0; // TODO: Need to get file size from StateManager
+      totalSent += sent;
+
+      fileProgresses[fileId] = {
+        sent,
+        total,
+        progress: total > 0 ? sent / total : 0,
+      };
+    });
+
+    return {
+      folderName,
+      totalSize: folderMeta.totalSize,
+      totalSent,
+      overallProgress:
+        folderMeta.totalSize > 0 ? totalSent / folderMeta.totalSize : 0,
+      fileCount: folderMeta.fileIds.length,
+      fileProgresses,
+    };
+  }
+
+  /**
+   * 🧹 Clean up progress tracking resources
+   */
+  cleanup(): void {
+    // SpeedCalculator internally automatically cleans up expired data
+    if (developmentEnv === "development")
+      postLogToBackend("[DEBUG] 🧹 ProgressTracker cleaned up");
+  }
+}

frontend/lib/transfer/StateManager.ts

@@ -0,0 +1,187 @@
+import { PeerState, CustomFile, FolderMeta } from "@/types/webrtc";
+// Simplified version no longer depends on TransferConfig's complex configuration
+
+/**
+ * 🚀 State management class
+ * Centrally manages all transfer-related state data
+ */
+export class StateManager {
+  private peerStates = new Map<string, PeerState>();
+  private pendingFiles = new Map<string, CustomFile>();
+  private pendingFolderMeta: Record<string, FolderMeta> = {};
+
+  // ===== Peer state management =====
+
+  /**
+   * Get or create peer state
+   */
+  public getPeerState(peerId: string): PeerState {
+    if (!this.peerStates.has(peerId)) {
+      this.peerStates.set(peerId, {
+        isSending: false,
+        bufferQueue: [],
+        readOffset: 0,
+        isReading: false,
+        currentFolderName: "",
+        totalBytesSent: {},
+        progressCallback: null,
+      });
+    }
+    return this.peerStates.get(peerId)!;
+  }
+
+  /**
+   * Update peer state
+   */
+  public updatePeerState(peerId: string, updates: Partial<PeerState>): void {
+    const currentState = this.getPeerState(peerId);
+    Object.assign(currentState, updates);
+  }
+
+  /**
+   * Reset peer state (when transfer is complete or error occurs)
+   */
+  public resetPeerState(peerId: string): void {
+    const peerState = this.getPeerState(peerId);
+    peerState.isSending = false;
+    peerState.readOffset = 0;
+    peerState.bufferQueue = [];
+    peerState.isReading = false;
+    // Preserve currentFolderName, totalBytesSent, progressCallback
+  }
+
+  /**
+   * Clear peer state immediately (for graceful disconnect)
+   */
+  public clearPeerState(peerId: string): void {
+    this.peerStates.delete(peerId);
+  }
+
+  // ===== File management =====
+
+  /**
+   * Add pending file to send
+   */
+  public addPendingFile(fileId: string, file: CustomFile): void {
+    this.pendingFiles.set(fileId, file);
+  }
+
+  /**
+   * Get pending file to send
+   */
+  public getPendingFile(fileId: string): CustomFile | undefined {
+    return this.pendingFiles.get(fileId);
+  }
+
+  /**
+   * Remove pending file to send
+   */
+  public removePendingFile(fileId: string): void {
+    this.pendingFiles.delete(fileId);
+  }
+
+  /**
+   * Get all pending files to send
+   */
+  public getAllPendingFiles(): Map<string, CustomFile> {
+    return new Map(this.pendingFiles);
+  }
+
+  // ===== Folder metadata management =====
+
+  /**
+   * Add or update folder metadata
+   */
+  public addFileToFolder(
+    folderName: string,
+    fileId: string,
+    fileSize: number
+  ): void {
+    if (!this.pendingFolderMeta[folderName]) {
+      this.pendingFolderMeta[folderName] = { totalSize: 0, fileIds: [] };
+    }
+
+    const folderMeta = this.pendingFolderMeta[folderName];
+    if (!folderMeta.fileIds.includes(fileId)) {
+      folderMeta.fileIds.push(fileId);
+      folderMeta.totalSize += fileSize;
+    }
+  }
+
+  /**
+   * Get folder metadata
+   */
+  public getFolderMeta(folderName: string): FolderMeta | undefined {
+    return this.pendingFolderMeta[folderName];
+  }
+
+  /**
+   * Get all folder metadata
+   */
+  public getAllFolderMeta(): Record<string, FolderMeta> {
+    return { ...this.pendingFolderMeta };
+  }
+  // ===== Progress tracking related state =====
+
+  /**
+   * Update file sent bytes
+   */
+  public updateFileBytesSent(
+    peerId: string,
+    fileId: string,
+    bytes: number
+  ): void {
+    const peerState = this.getPeerState(peerId);
+    if (!peerState.totalBytesSent[fileId]) {
+      peerState.totalBytesSent[fileId] = 0;
+    }
+    peerState.totalBytesSent[fileId] += bytes;
+  }
+
+  /**
+   * Get file sent bytes
+   */
+  public getFileBytesSent(peerId: string, fileId: string): number {
+    const peerState = this.peerStates.get(peerId);
+    return peerState?.totalBytesSent[fileId] || 0;
+  }
+
+  /**
+   * Calculate folder total sent bytes
+   */
+  public getFolderBytesSent(peerId: string, folderName: string): number {
+    const folderMeta = this.getFolderMeta(folderName);
+    const peerState = this.peerStates.get(peerId);
+
+    if (!folderMeta || !peerState) return 0;
+
+    let totalSent = 0;
+    folderMeta.fileIds.forEach((fileId) => {
+      totalSent += peerState.totalBytesSent[fileId] || 0;
+    });
+
+    return totalSent;
+  }
+
+  // ===== Cleanup and reset =====
+
+  /**
+   * Clean up all states (when system resets)
+   */
+  public cleanup(): void {
+    this.peerStates.clear();
+    this.pendingFiles.clear();
+    this.pendingFolderMeta = {};
+  }
+
+  /**
+   * Get state statistics (for debugging)
+   */
+  public getStateStats() {
+    return {
+      peerCount: this.peerStates.size,
+      pendingFileCount: this.pendingFiles.size,
+      folderCount: Object.keys(this.pendingFolderMeta).length,
+    };
+  }
+}

frontend/lib/transfer/StreamingFileReader.ts

@@ -0,0 +1,399 @@
+import { CustomFile } from "@/types/webrtc";
+import { TransferConfig } from "./TransferConfig";
+import { ChunkRangeCalculator } from "@/lib/utils/ChunkRangeCalculator";
+import { postLogToBackend } from "@/app/config/api";
+const developmentEnv = process.env.NODE_ENV;
+/**
+ * 🚀 Network chunk interface
+ */
+export interface NetworkChunk {
+  chunk: ArrayBuffer | null;
+  chunkIndex: number;
+  totalChunks: number;
+  fileOffset: number;
+  isLastChunk: boolean;
+}
+
+/**
+ * 🚀 High-performance streaming file reader
+ * Uses a two-layer buffering architecture: large batch reading + small network chunk sending
+ * Solves file reading performance bottleneck issues
+ */
+export class StreamingFileReader {
+  // Configuration parameters
+  private readonly BATCH_SIZE =
+    TransferConfig.FILE_CONFIG.CHUNK_SIZE *
+    TransferConfig.FILE_CONFIG.BATCH_SIZE; // 32MB batches
+  private readonly NETWORK_CHUNK_SIZE =
+    TransferConfig.FILE_CONFIG.NETWORK_CHUNK_SIZE; // 64KB network chunks
+  private readonly CHUNKS_PER_BATCH = this.BATCH_SIZE / this.NETWORK_CHUNK_SIZE; // 512 chunks
+
+  // File state
+  private file: File;
+  private fileReader: FileReader;
+  private totalFileSize: number;
+
+  // Batch buffering state
+  private currentBatch: ArrayBuffer | null = null; // Current 32MB batch data
+  private currentBatchStartOffset = 0; // Starting position of current batch in file
+  private currentChunkIndexInBatch = 0; // Index of current network chunk in batch
+
+  // Global state
+  private totalFileOffset = 0; // Current position in the entire file
+  private startChunkIndex = 0; // 🔧 Record the chunk index at the start of transmission
+  private isFinished = false;
+  private isReading = false; // Prevent concurrent reading
+
+  constructor(file: CustomFile, startOffset: number = 0) {
+    this.file = file;
+    this.totalFileSize = file.size;
+    this.totalFileOffset = startOffset;
+    // 🔧 Fix: When resuming, currentBatchStartOffset should start from startOffset
+    this.currentBatchStartOffset = startOffset;
+    this.fileReader = new FileReader();
+
+    // 🔧 Record the starting chunk index of the transfer, used for boundary detection
+    this.startChunkIndex = Math.floor(startOffset / this.NETWORK_CHUNK_SIZE);
+
+    if (developmentEnv === "development") {
+      const chunkRange = ChunkRangeCalculator.getChunkRange(
+        this.totalFileSize,
+        startOffset,
+        this.NETWORK_CHUNK_SIZE
+      );
+      postLogToBackend(
+        `[SEND-SUMMARY] File: ${file.name}, offset: ${startOffset}, startChunk: ${chunkRange.startChunk}, endChunk: ${chunkRange.endChunk}, willSend: ${chunkRange.totalChunks}, absoluteTotal: ${chunkRange.absoluteTotalChunks}`
+      );
+    }
+  }
+
+  /**
+   * 🎯 Core method: Get next 64KB network chunk
+   */
+  async getNextNetworkChunk(): Promise<NetworkChunk> {
+    // 1. Check if new batch needs to be loaded
+    if (this.needsNewBatch()) {
+      await this.loadNextBatch();
+    }
+
+    // 2. Check if end of file has been reached
+    if (this.isFinished || !this.currentBatch) {
+      return {
+        chunk: null,
+        chunkIndex: this.calculateGlobalChunkIndex(),
+        totalChunks: this.calculateTotalNetworkChunks(),
+        fileOffset: this.totalFileOffset,
+        isLastChunk: true,
+      };
+    }
+
+    // 3. Slice 64KB network chunk from current batch
+    const networkChunk = this.sliceNetworkChunkFromBatch();
+    const globalChunkIndex = this.calculateGlobalChunkIndex();
+    const isLast = this.isLastNetworkChunk(networkChunk);
+
+    // 4. Update state
+    this.updateChunkState(networkChunk);
+
+    // if (developmentEnv === "development") {
+    //   const totalChunks = this.calculateTotalNetworkChunks();
+
+    //   const isFirst = globalChunkIndex === this.startChunkIndex;
+    //   const expectedLastChunk = Math.floor(
+    //     (this.totalFileSize - 1) / this.NETWORK_CHUNK_SIZE
+    //   );
+    //   const isRealLast = isLast && globalChunkIndex === expectedLastChunk;
+
+    //   if (isFirst || isRealLast) {
+    //     postLogToBackend(
+    //       `[BOUNDARY] Chunk #${globalChunkIndex}/${totalChunks}, isFirst: ${isFirst}, isLast: ${isRealLast}, startIdx: ${this.startChunkIndex}, expectedLastIdx: ${expectedLastChunk}, size: ${networkChunk.byteLength}`
+    //     );
+    //   }
+    // }
+
+    return {
+      chunk: networkChunk,
+      chunkIndex: globalChunkIndex,
+      totalChunks: this.calculateTotalNetworkChunks(),
+      fileOffset: this.totalFileOffset - networkChunk.byteLength,
+      isLastChunk: isLast,
+    };
+  }
+
+  /**
+   * 🔍 Determine if new batch needs to be loaded
+   */
+  private needsNewBatch(): boolean {
+    return (
+      this.currentBatch === null || // No batch loaded yet
+      this.currentChunkIndexInBatch >= this.CHUNKS_PER_BATCH || // Current batch exhausted
+      this.isCurrentBatchEmpty() // Current batch has no data
+    );
+  }
+
+  /**
+   * 🔍 Check if current batch is empty
+   */
+  private isCurrentBatchEmpty(): boolean {
+    if (!this.currentBatch) return true;
+
+    const usedBytes = this.currentChunkIndexInBatch * this.NETWORK_CHUNK_SIZE;
+    return usedBytes >= this.currentBatch.byteLength;
+  }
+
+  /**
+   * 📥 Load next 32MB batch into memory
+   */
+  private async loadNextBatch(): Promise<void> {
+    if (this.isReading) {
+      // Prevent concurrent reading
+      while (this.isReading) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+      return;
+    }
+
+    this.isReading = true;
+    const startTime = performance.now();
+
+    try {
+      // 1. Clean up old batch memory
+      this.currentBatch = null;
+
+      // 2. Calculate size to read this time
+      const remainingFileSize = this.totalFileSize - this.totalFileOffset;
+      const batchSize = Math.min(this.BATCH_SIZE, remainingFileSize);
+
+      if (batchSize <= 0) {
+        this.isFinished = true;
+        return;
+      }
+
+      // 3. Perform large chunk file reading
+      const sliceStartTime = performance.now();
+      const fileSlice = this.file.slice(
+        this.totalFileOffset,
+        this.totalFileOffset + batchSize
+      );
+      const sliceTime = performance.now() - sliceStartTime;
+
+      // 4. Asynchronously read file data
+      const readStartTime = performance.now();
+      this.currentBatch = await this.readFileSlice(fileSlice);
+      const readTime = performance.now() - readStartTime;
+
+      const batchStartOffset = this.totalFileOffset;
+      this.currentBatchStartOffset = batchStartOffset;
+
+      // 🔧 Fix: Simplify index calculation logic within batch
+      // Since calculateGlobalChunkIndex now directly calculates based on totalFileOffset
+      // Indexing within a batch only needs to be calculated based on the starting position of the current batch
+      const chunkOffsetInBatch =
+        batchStartOffset -
+        Math.floor(batchStartOffset / this.BATCH_SIZE) * this.BATCH_SIZE;
+      this.currentChunkIndexInBatch = Math.floor(
+        chunkOffsetInBatch / this.NETWORK_CHUNK_SIZE
+      );
+
+      // Only output essential batch reading logs in development environment
+      if (developmentEnv === "development" && batchSize > this.BATCH_SIZE / 2) {
+        const totalTime = performance.now() - startTime;
+        const speedMBps = batchSize / 1024 / 1024 / (totalTime / 1000);
+        postLogToBackend(
+          `[BATCH-READ] 📖 size: ${(batchSize / 1024 / 1024).toFixed(
+            1
+          )}MB, speed: ${speedMBps.toFixed(1)}MB/s`
+        );
+      }
+    } catch (error) {
+      if (developmentEnv === "development") {
+        postLogToBackend(`[DEBUG] ❌ BATCH_READ failed: ${error}`);
+      }
+      throw new Error(`Failed to load file batch: ${error}`);
+    } finally {
+      this.isReading = false;
+    }
+  }
+
+  /**
+   * 📄 Perform file reading operation
+   */
+  private async readFileSlice(fileSlice: Blob): Promise<ArrayBuffer> {
+    return new Promise((resolve, reject) => {
+      this.fileReader.onload = () => {
+        const result = this.fileReader.result as ArrayBuffer;
+        if (result) {
+          resolve(result);
+        } else {
+          reject(new Error("FileReader result is null"));
+        }
+      };
+
+      this.fileReader.onerror = () => {
+        reject(
+          new Error(
+            `File reading failed: ${
+              this.fileReader.error?.message || "Unknown error"
+            }`
+          )
+        );
+      };
+
+      this.fileReader.readAsArrayBuffer(fileSlice);
+    });
+  }
+
+  /**
+   * ✂️ Slice 64KB network chunk from 32MB batch
+   * 🆕 Fix: Calculate directly based on the position of offset in the batch, avoiding complex batch internal index calculations
+   */
+  private sliceNetworkChunkFromBatch(): ArrayBuffer {
+    if (!this.currentBatch) {
+      throw new Error("No current batch available for slicing");
+    }
+
+    // 🆕 Calculated directly based on the position of offset in the batch to avoid index calculation errors within the batch
+    const offsetInBatch = this.totalFileOffset - this.currentBatchStartOffset;
+    const remainingInBatch = this.currentBatch.byteLength - offsetInBatch;
+    const chunkSize = Math.min(this.NETWORK_CHUNK_SIZE, remainingInBatch);
+
+    if (chunkSize <= 0) {
+      throw new Error("Invalid chunk size calculated");
+    }
+
+    const networkChunk = this.currentBatch.slice(
+      offsetInBatch,
+      offsetInBatch + chunkSize
+    );
+
+    // Delete frequent slice logs, only output when needed
+    return networkChunk;
+  }
+
+  /**
+   * 📊 Calculate global network chunk index
+   * 🔧 Simplified logic: directly calculate based on file offset to avoid batch boundary errors
+   */
+  private calculateGlobalChunkIndex(): number {
+    // Calculate chunk index directly based on current file offset, avoiding complex batch calculations, consistent with receiver
+    return Math.floor(this.totalFileOffset / this.NETWORK_CHUNK_SIZE);
+  }
+
+  /**
+   * 📈 Calculate total network chunk count
+   */
+  private calculateTotalNetworkChunks(): number {
+    return Math.ceil(this.totalFileSize / this.NETWORK_CHUNK_SIZE);
+  }
+
+  /**
+   * ⏭️ Update current processing state
+   */
+  private updateChunkState(chunk: ArrayBuffer): void {
+    this.currentChunkIndexInBatch++;
+    this.totalFileOffset += chunk.byteLength;
+
+    // Check if end of file has been reached
+    if (this.totalFileOffset >= this.totalFileSize) {
+      this.isFinished = true;
+    }
+  }
+
+  /**
+   * 🏁 Check if this is the last network chunk
+   */
+  private isLastNetworkChunk(chunk: ArrayBuffer): boolean {
+    return this.totalFileOffset + chunk.byteLength >= this.totalFileSize;
+  }
+
+  /**
+   * 📊 Get reading progress information
+   */
+  public getProgress(): {
+    readBytes: number;
+    totalBytes: number;
+    progressPercent: number;
+    currentBatchInfo?: {
+      batchStartOffset: number;
+      batchSize: number;
+      chunkIndex: number;
+      totalChunks: number;
+    };
+  } {
+    const progressPercent =
+      this.totalFileSize > 0
+        ? (this.totalFileOffset / this.totalFileSize) * 100
+        : 0;
+
+    const result = {
+      readBytes: this.totalFileOffset,
+      totalBytes: this.totalFileSize,
+      progressPercent,
+    } as any;
+
+    if (this.currentBatch) {
+      result.currentBatchInfo = {
+        batchStartOffset: this.currentBatchStartOffset,
+        batchSize: this.currentBatch.byteLength,
+        chunkIndex: this.currentChunkIndexInBatch,
+        totalChunks: Math.ceil(
+          this.currentBatch.byteLength / this.NETWORK_CHUNK_SIZE
+        ),
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * 🔄 Reset reader state (for restarting reading)
+   */
+  public reset(startOffset: number = 0): void {
+    this.totalFileOffset = startOffset;
+    this.isFinished = false;
+    this.isReading = false;
+    this.currentBatch = null;
+    // 🔧 Fix: Reset also needs to correctly set currentBatchStartOffset
+    this.currentBatchStartOffset = startOffset;
+    this.currentChunkIndexInBatch = 0; // Reset to 0, loadNextBatch will recalculate
+
+    if (developmentEnv === "development") {
+      postLogToBackend(
+        `[DEBUG] 🔄 StreamingFileReader reset - startOffset:${startOffset}`
+      );
+    }
+  }
+
+  /**
+   * 🧹 Cleanup and release resources
+   */
+  public cleanup(): void {
+    // Abort ongoing file reading
+    if (this.isReading) {
+      this.fileReader.abort();
+    }
+
+    // Clean up memory
+    this.currentBatch = null;
+    this.isFinished = true;
+    this.isReading = false;
+  }
+
+  /**
+   * 🔍 Get debug information
+   */
+  public getDebugInfo() {
+    return {
+      fileName: this.file.name,
+      fileSize: this.totalFileSize,
+      currentOffset: this.totalFileOffset,
+      isFinished: this.isFinished,
+      isReading: this.isReading,
+      hasBatch: !!this.currentBatch,
+      batchOffset: this.currentBatchStartOffset,
+      chunkInBatch: this.currentChunkIndexInBatch,
+      globalChunkIndex: this.calculateGlobalChunkIndex(),
+      totalChunks: this.calculateTotalNetworkChunks(),
+    };
+  }
+}

frontend/lib/transfer/TransferConfig.ts

@@ -0,0 +1,12 @@
+/**
+ * 🚀 Transfer configuration management class
+ * Centrally manages all file transfer related configuration parameters
+ */
+export class TransferConfig {
+  // File I/O related configuration
+  static readonly FILE_CONFIG = {
+    CHUNK_SIZE: 4194304, // 4MB - File reading chunk size, reduces FileReader calls
+    BATCH_SIZE: 8, // 8 chunks batch processing - 32MB batch processing improves performance
+    NETWORK_CHUNK_SIZE: 65536, // 64KB - WebRTC safe sending size, fixes sendData failed
+  } as const;
+}

frontend/lib/transfer/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 🚀 File transfer module unified export
+ * Provides modular file transfer services
+ */
+
+// Configuration management
+export { TransferConfig } from "./TransferConfig";
+
+// State management
+export { StateManager } from "./StateManager";
+
+// High-performance file reading
+export { StreamingFileReader } from "./StreamingFileReader";
+export type { NetworkChunk } from "./StreamingFileReader";
+
+// Network transmission
+export { NetworkTransmitter } from "./NetworkTransmitter";
+
+// Message handling
+export { MessageHandler } from "./MessageHandler";
+export type { MessageHandlerDelegate } from "./MessageHandler";
+
+// Progress tracking
+export { ProgressTracker } from "./ProgressTracker";
+export type { ProgressCallback } from "./ProgressTracker";
+
+// Main orchestrator
+export { FileTransferOrchestrator } from "./FileTransferOrchestrator";
+
+/**
+ * 🎯 Convenience creation function - Quick initialization of file transfer services
+ */
+import WebRTC_Initiator from "../webrtc_Initiator";
+import { FileTransferOrchestrator } from "./FileTransferOrchestrator";
+
+export function createFileTransferService(
+  webrtcConnection: WebRTC_Initiator
+): FileTransferOrchestrator {
+  return new FileTransferOrchestrator(webrtcConnection);
+}

frontend/lib/utils/ChunkRangeCalculator.ts

@@ -0,0 +1,82 @@
+/**
+ * 🚀 Chunk range calculation utilities
+ * Provides unified chunk calculation logic to ensure consistency between sender and receiver
+ */
+
+export class ChunkRangeCalculator {
+  /**
+   * Calculate chunk range for a file with given parameters
+   * This method ensures both sender and receiver use identical calculation logic
+   */
+  static getChunkRange(fileSize: number, startOffset: number, chunkSize: number) {
+    // Calculate starting chunk index
+    const startChunk = Math.floor(startOffset / chunkSize);
+    
+    // Calculate ending chunk index based on the last byte of the file
+    const lastByteIndex = fileSize - 1;
+    const endChunk = Math.floor(lastByteIndex / chunkSize);
+    
+    // Calculate total chunks to be sent/received (from startChunk to endChunk inclusive)
+    const totalChunks = endChunk - startChunk + 1;
+    
+    // Calculate absolute total chunks in the entire file
+    const absoluteTotalChunks = Math.ceil(fileSize / chunkSize);
+    
+    return { 
+      startChunk,           // First chunk index to process
+      endChunk,            // Last chunk index to process  
+      totalChunks,         // Number of chunks to process (for resume transfers)
+      absoluteTotalChunks  // Total chunks in the entire file
+    };
+  }
+
+  /**
+   * Calculate expected chunks count for resume transfer
+   * Identical to ReceptionConfig.calculateExpectedChunks()
+   */
+  static calculateExpectedChunks(fileSize: number, startOffset: number, chunkSize: number): number {
+    return Math.ceil((fileSize - startOffset) / chunkSize);
+  }
+
+  /**
+   * Get chunk index from file offset
+   * Identical to ReceptionConfig.getChunkIndexFromOffset()
+   */
+  static getChunkIndexFromOffset(offset: number, chunkSize: number): number {
+    return Math.floor(offset / chunkSize);
+  }
+
+  /**
+   * Get file offset from chunk index
+   * Identical to ReceptionConfig.getOffsetFromChunkIndex()
+   */
+  static getOffsetFromChunkIndex(chunkIndex: number, chunkSize: number): number {
+    return chunkIndex * chunkSize;
+  }
+
+  /**
+   * Validate chunk index within expected range
+   */
+  static isChunkIndexValid(
+    chunkIndex: number, 
+    startOffset: number, 
+    fileSize: number, 
+    chunkSize: number
+  ): boolean {
+    const range = this.getChunkRange(fileSize, startOffset, chunkSize);
+    return chunkIndex >= range.startChunk && chunkIndex <= range.endChunk;
+  }
+
+  /**
+   * Calculate relative chunk index from absolute chunk index
+   * Used by receiver to map sender's absolute index to local array index
+   */
+  static getRelativeChunkIndex(
+    absoluteChunkIndex: number, 
+    startOffset: number, 
+    chunkSize: number
+  ): number {
+    const startChunkIndex = this.getChunkIndexFromOffset(startOffset, chunkSize);
+    return absoluteChunkIndex - startChunkIndex;
+  }
+}

frontend/lib/webrtcService.ts

@@ -8,7 +8,6 @@ import {
   config,
 } from "@/app/config/environment";
 import { useFileTransferStore } from "@/stores/fileTransferStore";
-import type { CustomFile } from "@/types/webrtc";
 
 class WebRTCService {
   public sender: WebRTC_Initiator;
@@ -41,72 +40,73 @@ class WebRTCService {
   }
 
   private initializeEventHandlers(): void {
-    // 发送方事件处理
+    // Sender event handling
     this.sender.onConnectionStateChange = (state, peerId) => {
+      console.log(`[WebRTC Service] Sender connection state: ${state} for peer ${peerId}`);
+      
       useFileTransferStore.getState().setShareConnectionState(state as any);
-      useFileTransferStore
-        .getState()
-        .setSharePeerCount(this.sender.peerConnections.size);
-
       if (state === "connected") {
+        // update share peer count
+        useFileTransferStore.getState().setSharePeerCount(this.sender.peerConnections.size);
+        console.log(`[WebRTC Service] Sender connected, peer count: ${this.sender.peerConnections.size}`);
+        
         this.fileSender.setProgressCallback((fileId, progress, speed) => {
           useFileTransferStore
             .getState()
             .updateSendProgress(fileId, peerId, { progress, speed });
         }, peerId);
+      } else if (state === "failed" || state === "closed") {
+        this.handleConnectionDisconnect(peerId, true, `CONNECTION_${state.toUpperCase()}`);
       }
     };
 
-    this.sender.onDataChannelOpen = (peerId) => {
+    this.sender.onDataChannelOpen = (_peerId) => {
       useFileTransferStore.getState().setIsSenderInRoom(true);
-      // 自动广播当前内容
+      // Automatically broadcast current content
       this.broadcastDataToAllPeers();
     };
 
     this.sender.onPeerDisconnected = (peerId) => {
-      setTimeout(() => {
-        useFileTransferStore
-          .getState()
-          .setSharePeerCount(this.sender.peerConnections.size);
-      }, 0);
+      console.log(`[WebRTC Service] Sender peer disconnected: ${peerId}`);
+      this.handleConnectionDisconnect(peerId, true, "PEER_DISCONNECTED");
     };
 
     this.sender.onError = (error) => {
-      console.error("[WebRTC Service] 发送方错误:", error.message);
+      console.error("[WebRTC Service] Sender error:", error.message);
+      // Clear all states on error
+      this.clearAllTransferProgress();
     };
 
-    // 接收方事件处理
+    // Receiver event handling
     this.receiver.onConnectionStateChange = (state, peerId) => {
+      console.log(`[WebRTC Service] Receiver connection state: ${state} for peer ${peerId}`);
+      
       useFileTransferStore.getState().setRetrieveConnectionState(state as any);
-      useFileTransferStore
-        .getState()
-        .setRetrievePeerCount(this.receiver.peerConnections.size);
 
       if (state === "connected") {
+        // update retrieve peer count
+        useFileTransferStore.getState().setRetrievePeerCount(this.receiver.peerConnections.size);
+        console.log(`[WebRTC Service] Receiver connected, peer count: ${this.receiver.peerConnections.size}`);
+        
         this.fileReceiver.setProgressCallback((fileId, progress, speed) => {
           useFileTransferStore
             .getState()
             .updateReceiveProgress(fileId, peerId, { progress, speed });
         });
-      } else if (state === "failed" || state === "disconnected") {
-        const { isAnyFileTransferring } = useFileTransferStore.getState();
-        if (isAnyFileTransferring) {
-          this.fileReceiver.gracefulShutdown();
-        }
+      } else if (state === "failed" || state === "closed") {
+        this.handleConnectionDisconnect(peerId, false, `CONNECTION_${state.toUpperCase()}`);
       }
     };
 
     this.receiver.onConnectionEstablished = (peerId) => {
-      const store = useFileTransferStore.getState();
+      this.fileSender.handlePeerReconnection(peerId);
       useFileTransferStore.getState().setSenderDisconnected(false);
       useFileTransferStore.getState().setIsReceiverInRoom(true);
     };
 
     this.receiver.onPeerDisconnected = (peerId) => {
-      const store = useFileTransferStore.getState();
-
-      useFileTransferStore.getState().setSenderDisconnected(true);
-      useFileTransferStore.getState().setRetrievePeerCount(0);
+      console.log(`[WebRTC Service] Receiver peer disconnected: ${peerId}`);
+      this.handleConnectionDisconnect(peerId, false, "PEER_DISCONNECTED");
     };
 
     this.fileReceiver.onStringReceived = (data) => {
@@ -123,10 +123,10 @@ class WebRTCService {
     };
 
     this.fileReceiver.onFileReceived = async (file) => {
-      // 🔧 增强修复：确保Store状态更新完全同步，使用多重验证
+      // 🔧 Enhanced fix: Ensure Store state updates are fully synchronized with multiple verifications
       const store = useFileTransferStore.getState();
 
-      // 检查文件是否已经存在，避免重复添加
+      // Check if file already exists to avoid duplicates
       const existingFile = store.retrievedFiles.find(
         (f) => f.name === file.name && f.size === file.size
       );
@@ -134,31 +134,17 @@ class WebRTCService {
       if (!existingFile) {
         store.addRetrievedFile(file);
       }
-
-      // 🔧 额外确保：立即验证状态更新是否成功，并重试机制
-      let verificationAttempts = 0;
-      const maxVerificationAttempts = 3;
-
-      const verifyFileAdded = () => {
-        verificationAttempts++;
-        const updatedStore = useFileTransferStore.getState();
-        const fileExists = updatedStore.retrievedFiles.some(
-          (f) => f.name === file.name && f.size === file.size
-        );
-
-        if (!fileExists && verificationAttempts < maxVerificationAttempts) {
-          updatedStore.addRetrievedFile(file);
-          setTimeout(verifyFileAdded, 10);
-        }
-      };
-
-      // 立即进行第一次验证
-      verifyFileAdded();
     };
   }
 
-  // 业务方法
+  // Business methods
   public async joinRoom(roomId: string, isSender: boolean): Promise<void> {
+    // Ensure clean state before joining
+    if (!isSender) {
+      // Force reset FileReceiver state to prevent "already in progress" errors
+      this.fileReceiver.forceReset();
+    }
+
     const peer = isSender ? this.sender : this.receiver;
     await peer.joinRoom(roomId, isSender);
 
@@ -168,12 +154,17 @@ class WebRTCService {
     setInRoom(true);
   }
 
+
   public async leaveRoom(isSender: boolean): Promise<void> {
     if (isSender) {
+      // Clean up sender
+      this.fileSender.cleanup();
       await this.sender.leaveRoomAndCleanup();
       useFileTransferStore.getState().setIsSenderInRoom(false);
       useFileTransferStore.getState().setSharePeerCount(0);
     } else {
+      // Clean up receiver - force reset to ensure complete cleanup
+      this.fileReceiver.forceReset();
       await this.receiver.leaveRoomAndCleanup();
       useFileTransferStore.getState().setIsReceiverInRoom(false);
       useFileTransferStore.getState().setRetrievePeerCount(0);
@@ -184,7 +175,7 @@ class WebRTCService {
     const { shareContent, sendFiles } = useFileTransferStore.getState();
     const peerIds = Array.from(this.sender.peerConnections.keys());
     if (peerIds.length === 0) {
-      console.warn("[WebRTC Service] 没有连接的对等端进行广播");
+      console.warn("[WebRTC Service] No connected peers to broadcast to");
       return false;
     }
 
@@ -201,7 +192,7 @@ class WebRTCService {
       );
       return true;
     } catch (error) {
-      console.error("[WebRTC Service] 广播失败:", error);
+      console.error("[WebRTC Service] Broadcast failed:", error);
       return false;
     }
   }
@@ -224,20 +215,116 @@ class WebRTCService {
     return this.fileReceiver.saveType;
   }
 
-  public manualSafeSave(): void {
-    this.fileReceiver.gracefulShutdown();
+  private handleConnectionDisconnect(peerId: string, isSender: boolean, reason: string): void {
+    console.log(`[WebRTC Service] Connection disconnect: ${reason}, peer: ${peerId}, sender: ${isSender}`);
+    
+    // Immediately clean up the transfer status to avoid UI freezing
+    this.immediateTransferCleanup(peerId, isSender, reason);
+    
+    // update connection state
+    this.updateConnectionState(peerId, isSender);
+  }
+
+  // Immediately clean up the transfer status
+  private immediateTransferCleanup(peerId: string, isSender: boolean, reason: string): void {
+    const store = useFileTransferStore.getState();
+    
+    if (isSender) {
+      // Sender disconnected: clean up the sender related status
+      this.clearPeerTransferProgress(peerId, true);
+    } else {
+      // Receiver side: sender disconnected, need to clean up the receiver status
+      const { isAnyFileTransferring } = store;
+      
+      if (isAnyFileTransferring) {
+        console.log(`[WebRTC Service] Force cleaning receiver due to sender disconnect: ${reason}`);
+        
+        // Catch the error that gracefulShutdown may throw
+        try {
+          this.fileReceiver.gracefulShutdown(`SENDER_${reason}`);
+        } catch (error) {
+          console.log(`[WebRTC Service] Expected error during graceful shutdown:`, error instanceof Error ? error.message : String(error));
+        }
+      }
+      
+      this.clearPeerTransferProgress(peerId, false);
+    }
+  }
+
+  // update connection state
+  private updateConnectionState(_peerId: string, isSender: boolean): void {
+    const store = useFileTransferStore.getState();
+    
+    if (isSender) {
+      // Sender disconnected: clean up the sender related status
+      const currentShareCount = store.sharePeerCount;
+      store.setSharePeerCount(Math.max(0, currentShareCount - 1));
+      console.log(`[WebRTC Service] Sender peer count: ${currentShareCount} → ${Math.max(0, currentShareCount - 1)}`);
+    } else {
+      // Receiver side: sender disconnected, need to clean up the receiver status
+      store.setRetrievePeerCount(0);
+      store.setSenderDisconnected(true);
+      console.log(`[WebRTC Service] Receiver peer count set to 0`);
+    }
+  }
+
+  // Clear all transfer progress
+  private clearAllTransferProgress(): void {
+    const store = useFileTransferStore.getState();
+    store.setSendProgress({});
+    store.setReceiveProgress({});
+    store.setIsAnyFileTransferring(false);
+    console.log(`[WebRTC Service] Cleared all transfer progress`);
+  }
+
+  private clearPeerTransferProgress(peerId: string, isSender: boolean): void {
+    const store = useFileTransferStore.getState();
+    const progressState = isSender ? store.sendProgress : store.receiveProgress;
+
+    // Clear transfer progress for this peer
+    const newProgress = { ...progressState };
+    Object.keys(newProgress).forEach((fileId) => {
+      if (newProgress[fileId][peerId]) {
+        delete newProgress[fileId][peerId];
+        // If no other peers are transferring this file, remove the file record
+        if (Object.keys(newProgress[fileId]).length === 0) {
+          delete newProgress[fileId];
+        }
+      }
+    });
+
+    if (isSender) {
+      store.setSendProgress(newProgress);
+    } else {
+      store.setReceiveProgress(newProgress);
+    }
+
+    // Recalculate isAnyFileTransferring status
+    const allProgress = [
+      ...Object.values(isSender ? newProgress : store.sendProgress),
+      ...Object.values(isSender ? store.receiveProgress : newProgress),
+    ];
+    const hasActiveTransfers = allProgress.some((fileProgress: any) => {
+      return Object.values(fileProgress).some((progress: any) => {
+        return progress.progress > 0 && progress.progress < 1;
+      });
+    });
+
+    if (!hasActiveTransfers) {
+      store.setIsAnyFileTransferring(false);
+    }
   }
 
   public async cleanup(): Promise<void> {
-    console.log("[WebRTC Service] 开始清理...");
+    console.log("[WebRTC Service] Starting cleanup...");
     try {
       await Promise.all([
         this.sender.cleanUpBeforeExit(),
         this.receiver.cleanUpBeforeExit(),
       ]);
-      console.log("[WebRTC Service] 清理完成");
+      console.log("[WebRTC Service] Cleanup completed");
     } catch (error) {
-      console.error("[WebRTC Service] 清理过程中出错:", error);
+      console.error("[WebRTC Service] Error during cleanup:", error);
     }
   }
 }

frontend/lib/webrtc_Initiator.ts

@@ -1,7 +1,7 @@
 // Initiator flow: Join room; receive 'ready' event (this event is triggered by the socket server after a new recipient enters) -> createPeerConnection + createDataChannel -> createAndSendOffer
 import BaseWebRTC, { WebRTCConfig } from "./webrtc_base";
 import { postLogToBackend } from "@/app/config/api";
-const developmentEnv = process.env.NEXT_PUBLIC_development!; // Development environment
+const developmentEnv = process.env.NODE_ENV; // Development environment
 
 export default class WebRTC_Initiator extends BaseWebRTC {
   constructor(config: WebRTCConfig) {
@@ -16,7 +16,7 @@ export default class WebRTC_Initiator extends BaseWebRTC {
     });
     // Add listener for recipient's response
     this.socket.on("recipient-ready", ({ peerId }) => {
-      if (developmentEnv === "true")
+      if (developmentEnv === "development")
         postLogToBackend(
           `[Initiator] Received recipient-ready from: ${peerId}`
         );
@@ -32,7 +32,7 @@ export default class WebRTC_Initiator extends BaseWebRTC {
   private async handleReady({ peerId }: { peerId: string }): Promise<void> {
     // Recipient peerId
     // this.log('log',`Received ready signal from peer ${peerId}`);
-    if (developmentEnv === "true")
+    if (developmentEnv === "development")
       postLogToBackend(`Received ready signal from peer ${peerId}`);
     await this.createPeerConnection(peerId);
     await this.createDataChannel(peerId);
@@ -48,7 +48,7 @@ export default class WebRTC_Initiator extends BaseWebRTC {
     from: string;
   }): Promise<void> {
     // this.log('log',`Handling answer from peer ${from}`);
-    if (developmentEnv === "true")
+    if (developmentEnv === "development")
       postLogToBackend(`Handling answer from peer ${from}`);
     const peerConnection = this.peerConnections.get(from);
     if (!peerConnection) {
@@ -77,14 +77,16 @@ export default class WebRTC_Initiator extends BaseWebRTC {
     try {
       const dataChannel = peerConnection.createDataChannel("dataChannel", {
         ordered: true,
-        // reliable: true
       });
-      // this.log('log', `Created data channel for peer ${peerId}`);
 
-      dataChannel.bufferedAmountLowThreshold = 262144; //256 KB -- 可以根据需要调整
+      dataChannel.bufferedAmountLowThreshold = 262144; // 256KB for others
+
       this.setupDataChannel(dataChannel, peerId);
       this.dataChannels.set(peerId, dataChannel);
     } catch (error) {
+      postLogToBackend(
+        `Error creating DataChannel - peer: ${peerId}, error: ${error}`
+      );
       this.fireError(`Error creating data channel for peer ${peerId}`, {
         error,
         peerId,
@@ -94,7 +96,7 @@ export default class WebRTC_Initiator extends BaseWebRTC {
   // If it is the initiator, create and send an offer to the signaling server to negotiate a connection with the recipient.
   private async createAndSendOffer(peerId: string): Promise<void> {
     // this.log('log', `Creating and sending offer to ${peerId}`);
-    if (developmentEnv === "true")
+    if (developmentEnv === "development")
       postLogToBackend(`createAndSendOffer for peerId: ${peerId}`);
     const peerConnection = this.peerConnections.get(peerId);
     if (!peerConnection) {

frontend/lib/webrtc_Recipient.ts

@@ -1,7 +1,5 @@
 // Recipient flow: Join room; receive 'offer' event -> createPeerConnection + createDataChannel -> send answer
 import BaseWebRTC, { WebRTCConfig } from "./webrtc_base";
-import { postLogToBackend } from "@/app/config/api";
-const developmentEnv = process.env.NEXT_PUBLIC_development!; // Development environment
 
 interface AnswerPayload {
   answer: RTCSessionDescriptionInit;
@@ -106,7 +104,6 @@ export default class WebRTC_Recipient extends BaseWebRTC {
     }
 
     peerConnection.ondatachannel = (event) => {
-      // this.log('log', `Received data channel from peer ${peerId}`);
       this.setupDataChannel(event.channel, peerId);
       this.dataChannels.set(peerId, event.channel);
     };

frontend/lib/webrtc_base.ts

@@ -2,7 +2,7 @@
 import io, { Socket, ManagerOptions, SocketOptions } from "socket.io-client";
 import { WakeLockManager } from "./wakeLockManager";
 import { postLogToBackend } from "@/app/config/api";
-const developmentEnv = process.env.NEXT_PUBLIC_development!; // Development environment
+const developmentEnv = process.env.NODE_ENV; // Development environment
 
 export class WebRTCError extends Error {
   constructor(message: string, public context?: Record<string, any>) {
@@ -64,6 +64,8 @@ export default class BaseWebRTC {
   protected isPeerDisconnected: boolean; // Tracks P2P connection status
   protected reconnectionInProgress: boolean; // Prevents duplicate reconnections
   protected wakeLockManager: WakeLockManager;
+  // Graceful disconnect tracking
+  protected gracefullyDisconnectedPeers: Set<string>;
 
   constructor(config: WebRTCConfig) {
     this.iceServers = config.iceServers;
@@ -83,6 +85,7 @@ export default class BaseWebRTC {
     this.roomId = null;
     this.peerId = null; // Own ID
     this.isInRoom = false; // Whether the user has already joined a room
+    this.gracefullyDisconnectedPeers = new Set(); // Track peers that disconnected gracefully
     this.setupCommonSocketListeners();
 
     this.isInitiator = false;
@@ -128,7 +131,7 @@ export default class BaseWebRTC {
     this.socket.on("disconnect", () => {
       this.isInRoom = false;
       this.isSocketDisconnected = true;
-      if (developmentEnv === "true")
+      if (developmentEnv === "development")
         postLogToBackend(
           `${this.peerId} disconnect on socket,isInitiator:${this.isInitiator},isInRoom:${this.isInRoom}`
         );
@@ -150,7 +153,7 @@ export default class BaseWebRTC {
     if (this.isSocketDisconnected && this.isPeerDisconnected && this.roomId) {
       // Start reconnection only after both socket and P2P connections are disconnected
       this.reconnectionInProgress = true;
-      if (developmentEnv === "true") {
+      if (developmentEnv === "development") {
         postLogToBackend(
           `Starting reconnection, socket and peer both disconnected. isInitiator:${this.isInitiator}`
         );
@@ -311,7 +314,7 @@ export default class BaseWebRTC {
       disconnected: async () => {
         await this.cleanupExistingConnection(peerId);
         this.isPeerDisconnected = true;
-        if (developmentEnv === "true")
+        if (developmentEnv === "development")
           postLogToBackend(`p2p disconnected, isInitiator:${this.isInitiator}`);
         // Attempt to reconnect
         this.attemptReconnection();
@@ -352,11 +355,60 @@ export default class BaseWebRTC {
     };
 
     dataChannel.onmessage = (event) => {
-      this.onDataReceived?.(event.data, peerId);
+      // Enhanced data type detection - supports multiple binary data formats in Firefox
+      let dataType = "Unknown";
+      let dataSize = 0;
+
+      if (typeof event.data === "string") {
+        dataType = "String";
+        dataSize = event.data.length;
+      } else if (event.data instanceof ArrayBuffer) {
+        dataType = "ArrayBuffer";
+        dataSize = event.data.byteLength;
+      } else if (event.data instanceof Blob) {
+        dataType = "Blob";
+        dataSize = event.data.size;
+      } else if (event.data instanceof Uint8Array) {
+        dataType = "Uint8Array";
+        dataSize = event.data.byteLength;
+      } else if (ArrayBuffer.isView(event.data)) {
+        dataType = "TypedArray";
+        dataSize = event.data.byteLength;
+      } else {
+        // Detailed unknown type debug information
+        dataType = `Unknown(${Object.prototype.toString.call(event.data)})`;
+        dataSize =
+          event.data?.length || event.data?.size || event.data?.byteLength || 0;
+      }
+
+      if (this.onDataReceived) {
+        this.onDataReceived(event.data, peerId);
+      }
     };
 
-    dataChannel.onclose = () =>
+    dataChannel.onerror = (error) => {
+      // Check if this is a user-initiated disconnect (not a real error)
+      // The error parameter is an Event object, not an Error object
+      const errorTarget = error.target as RTCDataChannel;
+      const isUserDisconnect = 
+        errorTarget?.readyState === "closed" || 
+        error.type === "error";
+
+      if (isUserDisconnect) {
+        this.log("log", `Data channel closed by user for peer ${peerId}`, {
+          error,
+        });
+      } else {
+        this.log("error", `Data channel error for peer ${peerId}`, { error });
+      }
+    };
+
+    dataChannel.onclose = () => {
+      if (developmentEnv === "development") {
+        postLogToBackend(`DataChannel closed for peer: ${peerId}`);
+      }
       this.log("log", `Data channel with ${peerId} closed.`);
+    };
   }
   // Join a room. sendInitiatorOnline indicates whether to send "initiator online" message after joining.
   public async joinRoom(
@@ -390,7 +442,7 @@ export default class BaseWebRTC {
               roomId: this.roomId,
             });
           }
-          if (developmentEnv === "true")
+          if (developmentEnv === "development")
             postLogToBackend(
               `peerId:${this.socket.id} Successfully joined room: ${response.roomId},isInitiator:${this.isInitiator},isInRoom:${this.isInRoom}`
             );
@@ -398,7 +450,7 @@ export default class BaseWebRTC {
         } else {
           this.isInRoom = false;
           this.roomId = null;
-          if (developmentEnv === "true")
+          if (developmentEnv === "development")
             postLogToBackend(`Failed to join room,message:${response.message}`);
           this.fireError("Failed to join room", { message: response.message });
           reject(new Error(response.message));
@@ -431,26 +483,75 @@ export default class BaseWebRTC {
     }
   }
   // Send to a specific peer
-  protected sendToPeer(data: any, peerId: string): boolean {
+  public sendToPeer(data: any, peerId: string): boolean {
     const dataChannel = this.dataChannels.get(peerId);
     if (dataChannel?.readyState === "open") {
-      dataChannel.send(data);
-      return true;
+      try {
+        // Firefox compatibility debugging: Log sending details
+        const _dataType =
+          typeof data === "string"
+            ? "string"
+            : data instanceof ArrayBuffer
+            ? "ArrayBuffer"
+            : typeof data;
+        const _dataSize =
+          typeof data === "string"
+            ? data.length
+            : data instanceof ArrayBuffer
+            ? data.byteLength
+            : 0;
+
+        // if (developmentEnv === "development")
+        //   postLogToBackend(
+        //     `sendToPeer - type: ${dataType}, size: ${dataSize}, bufferedAmount: ${dataChannel.bufferedAmount}`
+        //   );
+
+        dataChannel.send(data);
+        return true;
+      } catch (error) {
+        postLogToBackend(`sendToPeer error: ${error}`);
+        this.log("error", `Error sending data to peer ${peerId}`, { error });
+        return false;
+      }
     }
 
+    postLogToBackend(
+      `DataChannel not ready - peerId: ${peerId}, state: ${
+        dataChannel?.readyState || "undefined"
+      }`
+    );
     this.log("warn", `Data channel not ready for peer ${peerId}. Retrying...`);
-    this.retryDataSend(data, peerId);
-    return false;
+    return this.retryDataSend(data, peerId);
   }
 
-  protected retryDataSend(data: any, peerId: string): void {
+  protected retryDataSend(data: any, peerId: string): boolean {
+    // Check if peer has gracefully disconnected - no need to retry
+    if (this.gracefullyDisconnectedPeers.has(peerId)) {
+      this.log(
+        "log",
+        `Peer ${peerId} has gracefully disconnected, skipping retry`
+      );
+      return false;
+    }
+
     const maxRetries = 5;
     let retryCount = 0;
+    let ret = false;
 
     const attemptSend = () => {
+      // Check again in case peer disconnected during retry
+      if (this.gracefullyDisconnectedPeers.has(peerId)) {
+        this.log(
+          "log",
+          `Peer ${peerId} gracefully disconnected during retry, stopping`
+        );
+        return;
+      }
+
       const dataChannel = this.dataChannels.get(peerId);
       if (dataChannel?.readyState === "open") {
         dataChannel.send(data);
+        ret = true;
       } else if (retryCount < maxRetries) {
         retryCount++;
         this.log(
@@ -466,6 +567,15 @@ export default class BaseWebRTC {
     };
 
     setTimeout(attemptSend, 100);
+    return ret;
+  }
+
+  /**
+   * Mark a peer as gracefully disconnected to prevent unnecessary retries
+   */
+  public markPeerGracefullyDisconnected(peerId: string): void {
+    this.gracefullyDisconnectedPeers.add(peerId);
+    this.log("log", `Marked peer ${peerId} as gracefully disconnected`);
   }
 
   protected async closeDataChannel(peerId: string): Promise<void> {
@@ -512,6 +622,7 @@ export default class BaseWebRTC {
     this.isPeerDisconnected = false;
     this.isSocketDisconnected = false;
     this.reconnectionInProgress = false;
+    this.gracefullyDisconnectedPeers.clear(); // Clear graceful disconnect tracking
 
     this.log(
       "log",
@@ -519,7 +630,7 @@ export default class BaseWebRTC {
     );
   }
   // Abstract method declaration
-  protected createDataChannel(peerId: string) {
+  protected createDataChannel(_peerId: string) {
     throw new Error("createDataChannel must be implemented by subclass");
   }
 }

frontend/stores/fileTransferStore.ts

@@ -2,14 +2,14 @@ import { create } from "zustand";
 import { CustomFile, FileMeta } from "@/types/webrtc";
 
 interface FileTransferState {
-  // 房间相关状态
+  // Room-related state
   shareRoomId: string;
   initShareRoomId: string;
   shareLink: string;
   shareRoomStatusText: string;
   retrieveRoomStatusText: string;
 
-  // WebRTC 连接状态 - 发送方
+  // WebRTC connection state - Sender
   shareConnectionState:
     | "idle"
     | "connecting"
@@ -19,7 +19,7 @@ interface FileTransferState {
   isSenderInRoom: boolean;
   sharePeerCount: number;
 
-  // WebRTC 连接状态 - 接收方
+  // WebRTC connection state - Receiver
   retrieveConnectionState:
     | "idle"
     | "connecting"
@@ -30,36 +30,36 @@ interface FileTransferState {
   retrievePeerCount: number;
   senderDisconnected: boolean;
 
-  // 文件传输状态
+  // File transfer state
   shareContent: string;
   sendFiles: CustomFile[];
   retrievedContent: string;
   retrievedFiles: CustomFile[];
   retrievedFileMetas: FileMeta[];
 
-  // 传输进度状态
+  // Transfer progress state
   sendProgress: Record<string, any>;
   receiveProgress: Record<string, any>;
   isAnyFileTransferring: boolean;
 
-  // UI 状态
+  // UI state
   activeTab: "send" | "retrieve";
   retrieveRoomIdInput: string;
   isDragging: boolean;
 
-  // 消息状态
+  // Message state
   shareMessage: string;
   retrieveMessage: string;
 
   // Actions
-  // 房间相关 actions
+  // Room-related actions
   setShareRoomId: (id: string) => void;
   setInitShareRoomId: (id: string) => void;
   setShareLink: (link: string) => void;
   setShareRoomStatusText: (text: string) => void;
   setRetrieveRoomStatusText: (text: string) => void;
 
-  // WebRTC 连接相关 actions
+  // WebRTC connection-related actions
   setShareConnectionState: (
     state: "idle" | "connecting" | "connected" | "disconnected" | "failed"
   ) => void;
@@ -72,7 +72,7 @@ interface FileTransferState {
   setRetrievePeerCount: (count: number) => void;
   setSenderDisconnected: (disconnected: boolean) => void;
 
-  // 文件传输相关 actions
+  // File transfer-related actions
   setShareContent: (content: string) => void;
   setSendFiles: (files: CustomFile[]) => void;
   addSendFiles: (files: CustomFile[]) => void;
@@ -82,7 +82,7 @@ interface FileTransferState {
   setRetrievedFileMetas: (metas: FileMeta[]) => void;
   addRetrievedFile: (file: CustomFile) => void;
 
-  // 传输进度相关 actions
+  // Transfer progress-related actions
   setSendProgress: (progress: Record<string, any>) => void;
   setReceiveProgress: (progress: Record<string, any>) => void;
   updateSendProgress: (
@@ -99,23 +99,23 @@ interface FileTransferState {
   clearReceiveProgress: (fileId: string, peerId: string) => void;
   setIsAnyFileTransferring: (transferring: boolean) => void;
 
-  // UI 状态相关 actions
+  // UI state-related actions
   setActiveTab: (tab: "send" | "retrieve") => void;
   setRetrieveRoomIdInput: (input: string) => void;
   setIsDragging: (dragging: boolean) => void;
 
-  // 消息相关 actions
+  // Message-related actions
   setShareMessage: (message: string) => void;
   setRetrieveMessage: (message: string) => void;
   setRetrieveRoomId: (input: string) => void;
 
-  // 重置相关 actions
+  // Reset-related actions
   resetReceiverState: () => void;
   resetSenderApp: () => void;
 }
 
 export const useFileTransferStore = create<FileTransferState>()((set, get) => ({
-  // 初始状态
+  // Initial state
   shareRoomId: "",
   initShareRoomId: "",
   shareLink: "",
@@ -142,14 +142,14 @@ export const useFileTransferStore = create<FileTransferState>()((set, get) => ({
   shareMessage: "",
   retrieveMessage: "",
 
-  // Actions 实现
+  // Actions implementation
   setShareRoomId: (id) => set({ shareRoomId: id }),
   setInitShareRoomId: (id) => set({ initShareRoomId: id }),
   setShareLink: (link) => set({ shareLink: link }),
   setShareRoomStatusText: (text) => set({ shareRoomStatusText: text }),
   setRetrieveRoomStatusText: (text) => set({ retrieveRoomStatusText: text }),
 
-  // WebRTC 连接相关 actions
+  // WebRTC connection-related actions
   setShareConnectionState: (state) => set({ shareConnectionState: state }),
   setIsSenderInRoom: (isInRoom) => set({ isSenderInRoom: isInRoom }),
   setSharePeerCount: (count) => set({ sharePeerCount: count }),
@@ -238,18 +238,11 @@ export const useFileTransferStore = create<FileTransferState>()((set, get) => ({
   setRetrieveMessage: (message) => set({ retrieveMessage: message }),
 
   resetReceiverState: () => {
-    // 🔧 清理 FileReceiver 的内部状态（通过 Service 层）
-    try {
-      const { webrtcService } = require("@/lib/webrtcService");
-      webrtcService.fileReceiver.gracefulShutdown();
-    } catch (error) {
-      console.warn(`[DEBUG] ⚠️ 清理 FileReceiver 状态失败:`, error);
-    }
-
+    // 🔧 Only reset Store state - FileReceiver cleanup is handled by webrtcService.leaveRoom()
     set({
       retrievedContent: "",
       retrievedFiles: [],
-      retrievedFileMetas: [], // 清空 Store 中的文件元数据
+      retrievedFileMetas: [], // Clear file metadata in Store
       retrievePeerCount: 0,
       senderDisconnected: false,
       receiveProgress: {},

frontend/types/messages.ts

@@ -174,9 +174,11 @@ export type FileTransferButton = {
   CurrentFileTransferring_tips: string;
   OtherFileTransferring_tips: string;
   download_tips: string;
+  PendingSave_tips: string;
   Saved_dis: string;
   Waiting_dis: string;
   Download_dis: string;
+  Save_dis: string;
 };
 
 export type FileListDisplay = {
@@ -191,9 +193,6 @@ export type FileListDisplay = {
   PopupDialog_description: string;
   chooseSavePath_tips: string;
   chooseSavePath_dis: string;
-  safeSave_dis: string;
-  safeSave_tooltip: string;
-  safeSaveSuccessMsg: string;
 };
 
 export type RetrieveMethod = {
@@ -243,7 +242,8 @@ export type ClipboardAppHtml = {
   Copy_dis: string;
   inputRoomIdprompt: string;
   joinRoomBtn: string;
-  generateRoomId_tips: string;
+  generateSimpleId_tips: string;
+  generateRandomId_tips: string;
   readClipboardToRoomId: string;
   enterRoomID_placeholder: string;
   retrieveMethod: string;
@@ -263,12 +263,17 @@ export type ClipboardApp = {
   waitting_tips: string;
   joinRoom: JoinRoom;
   pickSaveMsg: string;
+  pickSaveUnsupported: string;
+  pickSaveSuccess: string;
+  pickSaveError: string;
   roomStatus: RoomStatus;
   html: ClipboardAppHtml;
   fileExistMsg?: string;
   noFilesForFolderMsg?: string;
   zipError?: string;
   fileNotFoundMsg?: string;
+  confirmLeaveWhileTransferring: string;
+  leaveWhileTransferringSuccess: string;
 };
 
 export type Home = {
@@ -305,4 +310,4 @@ export type Text = {
 export type Messages = {
   meta: Meta;
   text: Text;
-};
+};

frontend/types/webrtc.ts

@@ -29,11 +29,6 @@ export interface FileRequest {
   offset?: number; // Optional: byte offset to resume from
 }
 
-export interface FileAck {
-  type: "fileAck";
-  fileId: string;
-}
-
 export interface StringMetadata {
   type: "stringMetadata";
   length: number;
@@ -46,24 +41,44 @@ export interface StringChunk {
   total: number;
 }
 
-export interface FileEnd {
-  type: "fileEnd";
+// Receiver-initiated completion confirmation message
+export interface FileReceiveComplete {
+  type: "fileReceiveComplete";
   fileId: string;
+  receivedSize: number;
+  receivedChunks: number;
+  storeUpdated: boolean; // Confirm Store has been updated
 }
 
-export interface FolderComplete {
-  type: "FolderComplete";
+export interface FolderReceiveComplete {
+  type: "folderReceiveComplete";
   folderName: string;
+  completedFileIds: string[];
+  allStoreUpdated: boolean; // Confirm all files have been added to Store
 }
 
+// 🚀 New: Chunk metadata structure embedded in data packets
+export interface EmbeddedChunkMeta {
+  chunkIndex: number; // Data chunk index, starting from 0  
+  totalChunks: number; // Total number of data chunks
+  chunkSize: number; // Data chunk size (excluding metadata portion)
+  isLastChunk: boolean; // Whether this is the last data chunk
+  fileOffset: number; // Offset in the file
+  fileId: string; // File ID, used for matching
+}
+// Note: EmbeddedChunkMeta is not in WebRTCMessage as it is embedded within binary data
+
+// 🚀 Binary structure of fused packets:
+// [4 bytes: metadata length] + [JSON metadata] + [actual chunk data]
+// All file transfers use this format uniformly to completely solve Firefox out-of-order issues
+
 export type WebRTCMessage =
   | fileMetadata
   | FileRequest
-  | FileAck
   | StringMetadata
   | StringChunk
-  | FileEnd
-  | FolderComplete;
+  | FileReceiveComplete
+  | FolderReceiveComplete;
 
 export interface FolderMeta {
   totalSize: number;
@@ -96,5 +111,4 @@ export interface FileHandlers {
   string: (data: any, peerId: string) => void;
   stringMetadata: (data: any, peerId: string) => void;
   fileMeta: (data: any, peerId: string) => void;
-  fileEnd: (data: any) => Promise<void>;
 }