improve code quality and user experience

Author: tw93

bin/builders/BaseBuilder.ts

@@ -173,6 +173,7 @@ export default abstract class BaseBuilder {
       `cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`,
       this.getBuildTimeout(),
       buildEnv,
+      this.options.debug,
     );
 
     // Copy app

bin/helpers/merge.ts

@@ -7,6 +7,13 @@ import { generateSafeFilename, generateIdentifierSafeName } from '@/utils/name';
 import { PakeAppOptions, PlatformMap } from '@/types';
 import { tauriConfigDirectory, npmDirectory } from '@/utils/dir';
 
+/**
+ * Helper function to generate safe lowercase app name for file paths
+ */
+function getSafeAppName(name: string): string {
+  return generateSafeFilename(name).toLowerCase();
+}
+
 export async function mergeConfig(
   url: string,
   options: PakeAppOptions,
@@ -153,7 +160,7 @@ export async function mergeConfig(
     delete tauriConf.bundle.linux.deb.files;
 
     // Generate correct desktop file configuration
-    const appNameSafe = generateSafeFilename(name).toLowerCase();
+    const appNameSafe = getSafeAppName(name);
     const identifier = `com.pake.${appNameSafe}`;
     const desktopFileName = `${identifier}.desktop`;
 
@@ -212,22 +219,23 @@ StartupNotify=true
   }
 
   // Set icon.
+  const safeAppName = getSafeAppName(name);
   const platformIconMap: PlatformMap = {
     win32: {
       fileExt: '.ico',
-      path: `png/${generateSafeFilename(name).toLowerCase()}_256.ico`,
+      path: `png/${safeAppName}_256.ico`,
       defaultIcon: 'png/icon_256.ico',
       message: 'Windows icon must be .ico and 256x256px.',
     },
     linux: {
       fileExt: '.png',
-      path: `png/${generateSafeFilename(name).toLowerCase()}_512.png`,
+      path: `png/${safeAppName}_512.png`,
       defaultIcon: 'png/icon_512.png',
       message: 'Linux icon must be .png and 512x512px.',
     },
     darwin: {
       fileExt: '.icns',
-      path: `icons/${generateSafeFilename(name).toLowerCase()}.icns`,
+      path: `icons/${safeAppName}.icns`,
       defaultIcon: 'icons/icon.icns',
       message: 'macOS icon must be .icns type.',
     },
@@ -278,9 +286,9 @@ StartupNotify=true
       if (iconExt == '.png' || iconExt == '.ico') {
         const trayIcoPath = path.join(
           npmDirectory,
-          `src-tauri/png/${generateSafeFilename(name).toLowerCase()}${iconExt}`,
+          `src-tauri/png/${safeAppName}${iconExt}`,
         );
-        trayIconPath = `png/${generateSafeFilename(name).toLowerCase()}${iconExt}`;
+        trayIconPath = `png/${safeAppName}${iconExt}`;
         await fsExtra.copy(systemTrayIcon, trayIcoPath);
       } else {
         logger.warn(

dist/cli.js

@@ -422,6 +422,12 @@ function generateIdentifierSafeName(name) {
     return cleaned;
 }
 
+/**
+ * Helper function to generate safe lowercase app name for file paths
+ */
+function getSafeAppName(name) {
+    return generateSafeFilename(name).toLowerCase();
+}
 async function mergeConfig(url, options, tauriConf) {
     // Ensure .pake directory exists and copy source templates if needed
     const srcTauriDir = path.join(npmDirectory, 'src-tauri');
@@ -512,7 +518,7 @@ async function mergeConfig(url, options, tauriConf) {
         // Remove hardcoded desktop files and regenerate with correct app name
         delete tauriConf.bundle.linux.deb.files;
         // Generate correct desktop file configuration
-        const appNameSafe = generateSafeFilename(name).toLowerCase();
+        const appNameSafe = getSafeAppName(name);
         const identifier = `com.pake.${appNameSafe}`;
         const desktopFileName = `${identifier}.desktop`;
         // Create desktop file content
@@ -563,22 +569,23 @@ StartupNotify=true
         }
     }
     // Set icon.
+    const safeAppName = getSafeAppName(name);
     const platformIconMap = {
         win32: {
             fileExt: '.ico',
-            path: `png/${generateSafeFilename(name).toLowerCase()}_256.ico`,
+            path: `png/${safeAppName}_256.ico`,
             defaultIcon: 'png/icon_256.ico',
             message: 'Windows icon must be .ico and 256x256px.',
         },
         linux: {
             fileExt: '.png',
-            path: `png/${generateSafeFilename(name).toLowerCase()}_512.png`,
+            path: `png/${safeAppName}_512.png`,
             defaultIcon: 'png/icon_512.png',
             message: 'Linux icon must be .png and 512x512px.',
         },
         darwin: {
             fileExt: '.icns',
-            path: `icons/${generateSafeFilename(name).toLowerCase()}.icns`,
+            path: `icons/${safeAppName}.icns`,
             defaultIcon: 'icons/icon.icns',
             message: 'macOS icon must be .icns type.',
         },
@@ -622,8 +629,8 @@ StartupNotify=true
             // 需要判断图标格式，默认只支持ico和png两种
             let iconExt = path.extname(systemTrayIcon).toLowerCase();
             if (iconExt == '.png' || iconExt == '.ico') {
-                const trayIcoPath = path.join(npmDirectory, `src-tauri/png/${generateSafeFilename(name).toLowerCase()}${iconExt}`);
-                trayIconPath = `png/${generateSafeFilename(name).toLowerCase()}${iconExt}`;
+                const trayIcoPath = path.join(npmDirectory, `src-tauri/png/${safeAppName}${iconExt}`);
+                trayIconPath = `png/${safeAppName}${iconExt}`;
                 await fsExtra.copy(systemTrayIcon, trayIcoPath);
             }
             else {
@@ -799,7 +806,7 @@ class BaseBuilder {
             ...this.getBuildEnvironment(),
             ...(process.env.NO_STRIP && { NO_STRIP: process.env.NO_STRIP }),
         };
-        await shellExec(`cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`, this.getBuildTimeout(), buildEnv);
+        await shellExec(`cd "${npmDirectory}" && ${this.getBuildCommand(packageManager)}`, this.getBuildTimeout(), buildEnv, this.options.debug);
         // Copy app
         const fileName = this.getFileName();
         const fileType = this.getFileType(target);

docs/advanced-usage.md

@@ -38,6 +38,44 @@ document.addEventListener("keydown", (e) => {
 });
 ```
 
+## Built-in Features
+
+### Download Error Notifications
+
+Pake automatically provides user-friendly download error notifications:
+
+**Features:**
+
+- **Bilingual Support**: Automatically detects browser language (Chinese/English)
+- **System Notifications**: Uses native OS notifications when permission is granted
+- **Graceful Fallback**: Falls back to console logging if notifications are unavailable
+- **Comprehensive Coverage**: Handles all download types (HTTP, Data URI, Blob)
+
+**User Experience:**
+
+When a download fails, users will see a notification:
+
+- English: "Download Error - Download failed: filename.pdf"
+- Chinese: "下载错误 - 下载失败: filename.pdf"
+
+**Requesting Notification Permission:**
+
+To enable notifications, add this to your injected JavaScript:
+
+```javascript
+// Request notification permission on app start
+if (window.Notification && Notification.permission === "default") {
+  Notification.requestPermission();
+}
+```
+
+The download system automatically handles:
+
+- Regular HTTP(S) downloads
+- Data URI downloads (base64 encoded files)
+- Blob URL downloads (dynamically generated files)
+- Context menu initiated downloads
+
 ## Container Communication
 
 Send messages between web content and Pake container.

docs/advanced-usage_CN.md

@@ -40,6 +40,41 @@
   });
   ```
 
+## 内置功能
+
+### 下载错误通知
+
+Pake 自动提供用户友好的下载错误通知：
+
+**功能特性：**
+- **双语支持**：自动检测浏览器语言（中文/英文）
+- **系统通知**：在授予权限后使用原生操作系统通知
+- **优雅降级**：如果通知不可用则降级到控制台日志
+- **全面覆盖**：处理所有下载类型（HTTP、Data URI、Blob）
+
+**用户体验：**
+
+当下载失败时，用户将看到通知：
+- 英文："Download Error - Download failed: filename.pdf"
+- 中文："下载错误 - 下载失败: filename.pdf"
+
+**请求通知权限：**
+
+要启用通知，请在注入的 JavaScript 中添加：
+
+```javascript
+// 在应用启动时请求通知权限
+if (window.Notification && Notification.permission === "default") {
+  Notification.requestPermission();
+}
+```
+
+下载系统自动处理：
+- 常规 HTTP(S) 下载
+- Data URI 下载（base64 编码文件）
+- Blob URL 下载（动态生成的文件）
+- 右键菜单发起的下载
+
 ## 容器通信
 
 在网页内容和 Pake 容器之间发送消息。

src-tauri/src/inject/event.js

@@ -148,6 +148,22 @@ function isChineseLanguage(language = getUserLanguage()) {
   );
 }
 
+// User notification helper
+function showDownloadError(filename) {
+  const isChinese = isChineseLanguage();
+  const message = isChinese
+    ? `下载失败: ${filename}`
+    : `Download failed: ${filename}`;
+
+  if (window.Notification && Notification.permission === "granted") {
+    new Notification(isChinese ? "下载错误" : "Download Error", {
+      body: message,
+    });
+  } else {
+    console.error(message);
+  }
+}
+
 // Unified file detection - replaces both isDownloadLink and isFileLink
 function isDownloadableFile(url) {
   try {
@@ -251,7 +267,7 @@ document.addEventListener("DOMContentLoaded", () => {
       }
 
       // write the ArrayBuffer to a binary, and you're done
-      const userLanguage = navigator.language || navigator.userLanguage;
+      const userLanguage = getUserLanguage();
       invoke("download_file_by_binary", {
         params: {
           filename,
@@ -260,16 +276,18 @@ document.addEventListener("DOMContentLoaded", () => {
         },
       }).catch((error) => {
         console.error("Failed to download data URI file:", filename, error);
+        showDownloadError(filename);
       });
     } catch (error) {
       console.error("Failed to process data URI:", dataURI, error);
+      showDownloadError(filename || "file");
     }
   }
 
   function downloadFromBlobUrl(blobUrl, filename) {
     convertBlobUrlToBinary(blobUrl)
       .then((binary) => {
-        const userLanguage = navigator.language || navigator.userLanguage;
+        const userLanguage = getUserLanguage();
         invoke("download_file_by_binary", {
           params: {
             filename,
@@ -278,10 +296,12 @@ document.addEventListener("DOMContentLoaded", () => {
           },
         }).catch((error) => {
           console.error("Failed to download blob file:", filename, error);
+          showDownloadError(filename);
         });
       })
       .catch((error) => {
         console.error("Failed to convert blob to binary:", blobUrl, error);
+        showDownloadError(filename);
       });
   }
 
@@ -659,13 +679,16 @@ document.addEventListener("DOMContentLoaded", () => {
       }
     } else {
       // Regular HTTP(S) image
-      const userLanguage = navigator.language || navigator.userLanguage;
+      const userLanguage = getUserLanguage();
       invoke("download_file", {
         params: {
           url: imageUrl,
           filename: filename,
           language: userLanguage,
         },
+      }).catch((error) => {
+        console.error("Failed to download image:", filename, error);
+        showDownloadError(filename);
       });
     }
   }
@@ -713,7 +736,7 @@ document.addEventListener("DOMContentLoaded", () => {
 
   // Simplified menu builder
   function buildMenuItems(type, data) {
-    const userLanguage = navigator.language || navigator.userLanguage;
+    const userLanguage = getUserLanguage();
     const items = [];
 
     switch (type) {
@@ -740,6 +763,9 @@ document.addEventListener("DOMContentLoaded", () => {
               const filename = getFilenameFromUrl(data.url);
               invoke("download_file", {
                 params: { url: data.url, filename, language: userLanguage },
+              }).catch((error) => {
+                console.error("Failed to download file:", filename, error);
+                showDownloadError(filename);
               });
             }),
           );

tests/index.js

@@ -12,6 +12,7 @@ import fs from "fs";
 import path from "path";
 import ora from "ora";
 import config, { TIMEOUTS, TEST_URLS } from "./config.js";
+import { runHelperTests } from "./unit/helpers.test.js";
 
 class PakeTestRunner {
   constructor() {
@@ -42,6 +43,12 @@ class PakeTestRunner {
       console.log("📋 Running Unit Tests...");
       await this.runUnitTests();
       testCount++;
+
+      // Run helper function tests
+      const helperTestsPassed = await runHelperTests();
+      if (!helperTestsPassed) {
+        console.log("⚠️  Some helper tests failed");
+      }
     }
 
     if (integration && !quick) {