feat(WebServer): add LVGL binary image preview via icu tool

Double-click .bin files to preview LVGL images: download from device,
convert to PNG via 'icu convert /dev/stdin --stdout' pipe (no temp
files), display in image preview tab. If icu is not installed, prompt
user to open https://i.to01.icu for installation.

Author: FASTSHIFT

Tools/WebServer/app/routes/files.py

@@ -216,3 +216,65 @@ def api_file_write_binary():
         return jsonify({"success": False, "error": f"Invalid hex data: {e}"})
     except Exception as e:
         return jsonify({"success": False, "error": str(e)})
+
+
+@bp.route("/convert/lvgl-to-png", methods=["POST"])
+def api_convert_lvgl_to_png():
+    """Convert LVGL binary image to PNG using icu CLI tool.
+
+    JSON body:
+        data: base64-encoded LVGL binary image data
+
+    Returns:
+        JSON with base64-encoded PNG data
+    """
+    import base64
+    import shutil
+    import subprocess
+
+    data = request.json or {}
+    b64_data = data.get("data", "")
+
+    if not b64_data:
+        return jsonify({"success": False, "error": "No data provided"})
+
+    # Check if icu tool is available
+    icu_path = shutil.which("icu")
+    if not icu_path:
+        return jsonify({"success": False, "error": "icu tool not installed"})
+
+    try:
+        bin_data = base64.b64decode(b64_data)
+    except Exception as e:
+        return jsonify({"success": False, "error": f"Invalid base64 data: {e}"})
+
+    try:
+        result = subprocess.run(
+            [
+                icu_path,
+                "convert",
+                "/dev/stdin",
+                "-f",
+                "lvgl-v9",
+                "-F",
+                "png",
+                "--stdout",
+            ],
+            input=bin_data,
+            capture_output=True,
+            timeout=10,
+        )
+
+        if result.returncode != 0 or not result.stdout:
+            error_msg = result.stderr.decode("utf-8", errors="replace").strip()
+            return jsonify(
+                {"success": False, "error": error_msg or "Conversion failed"}
+            )
+
+        png_b64 = base64.b64encode(result.stdout).decode("ascii")
+        return jsonify({"success": True, "data": png_b64, "size": len(result.stdout)})
+
+    except subprocess.TimeoutExpired:
+        return jsonify({"success": False, "error": "Conversion timed out"})
+    except Exception as e:
+        return jsonify({"success": False, "error": str(e)})

Tools/WebServer/static/js/features/transfer.js

@@ -496,6 +496,8 @@ async function refreshDeviceFiles() {
         refreshDeviceFiles();
       } else if (_isImageFile(entry.name)) {
         previewDeviceImage(item.dataset.path, entry.name);
+      } else if (_isLvglBinFile(entry.name)) {
+        previewDeviceImage(item.dataset.path, entry.name, true);
       } else if (_isTextFile(entry.name)) {
         openDeviceTextFile(item.dataset.path, entry.name);
       }
@@ -776,6 +778,55 @@ function _isImageFile(name) {
   return _IMAGE_EXTENSIONS.some((ext) => lower.endsWith(ext));
 }
 
+/** LVGL binary image extensions */
+const _LVGL_BIN_EXTENSIONS = ['.bin'];
+
+/**
+ * Check if a filename is an LVGL binary image file.
+ */
+function _isLvglBinFile(name) {
+  const lower = name.toLowerCase();
+  return _LVGL_BIN_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+
+/**
+ * Convert LVGL binary data to PNG via backend icu tool.
+ * @param {Blob} blob - LVGL binary data
+ * @returns {Promise<{success: boolean, blob?: Blob, error?: string}>}
+ */
+async function convertLvglToPng(blob) {
+  try {
+    const arrayBuffer = await blob.arrayBuffer();
+    const bytes = new Uint8Array(arrayBuffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    const b64 = btoa(binary);
+
+    const res = await fetch('/api/convert/lvgl-to-png', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ data: b64 }),
+    });
+    const data = await res.json();
+
+    if (!data.success) {
+      return { success: false, error: data.error || 'Conversion failed' };
+    }
+
+    const pngBinary = atob(data.data);
+    const pngBytes = new Uint8Array(pngBinary.length);
+    for (let i = 0; i < pngBinary.length; i++) {
+      pngBytes[i] = pngBinary.charCodeAt(i);
+    }
+    const pngBlob = new Blob([pngBytes], { type: 'image/png' });
+    return { success: true, blob: pngBlob };
+  } catch (e) {
+    return { success: false, error: e.message || String(e) };
+  }
+}
+
 /* ===========================
    TEXT FILE SUPPORT
    =========================== */
@@ -1335,8 +1386,11 @@ async function refreshPreviewTab(tabId) {
 /**
  * Preview an image file from the device in an editor tab.
  * Downloads the file, creates a blob URL, and displays it in a new tab.
+ * @param {string} remotePath - File path on device
+ * @param {string} fileName - File name for display
+ * @param {boolean} isLvgl - If true, convert LVGL binary to PNG before display
  */
-async function previewDeviceImage(remotePath, fileName) {
+async function previewDeviceImage(remotePath, fileName, isLvgl = false) {
   const state = window.FPBState;
   if (!state.isConnected) {
     log.error('Not connected');
@@ -1376,20 +1430,48 @@ async function previewDeviceImage(remotePath, fileName) {
       return;
     }
 
-    // Create blob URL from downloaded data
-    const ext = fileName.split('.').pop().toLowerCase();
-    const mimeMap = {
-      png: 'image/png',
-      jpg: 'image/jpeg',
-      jpeg: 'image/jpeg',
-      gif: 'image/gif',
-      bmp: 'image/bmp',
-      svg: 'image/svg+xml',
-      webp: 'image/webp',
-      ico: 'image/x-icon',
-    };
-    const mime = mimeMap[ext] || 'image/png';
-    const blob = result.blob || new Blob([result.data], { type: mime });
+    let blob;
+    if (isLvgl) {
+      // Convert LVGL binary to PNG via backend
+      const rawBlob = result.blob || new Blob([result.data]);
+      log.info('Converting LVGL image...');
+      const convResult = await convertLvglToPng(rawBlob);
+      if (!convResult.success) {
+        if (
+          convResult.error &&
+          convResult.error.includes('icu tool not installed')
+        ) {
+          const install = confirm(
+            t(
+              'transfer.icu_not_installed',
+              'The "icu" tool is required to preview LVGL images but is not installed.\nOpen the installation page?',
+            ),
+          );
+          if (install) {
+            window.open('https://i.to01.icu', '_blank');
+          }
+        } else {
+          log.error(`LVGL convert failed: ${convResult.error}`);
+        }
+        return;
+      }
+      blob = convResult.blob;
+    } else {
+      // Standard image
+      const ext = fileName.split('.').pop().toLowerCase();
+      const mimeMap = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        bmp: 'image/bmp',
+        svg: 'image/svg+xml',
+        webp: 'image/webp',
+        ico: 'image/x-icon',
+      };
+      const mime = mimeMap[ext] || 'image/png';
+      blob = result.blob || new Blob([result.data], { type: mime });
+    }
     const blobUrl = URL.createObjectURL(blob);
 
     // Create editor tab
@@ -2336,6 +2418,8 @@ window.hideTransferContextMenu = hideTransferContextMenu;
 window.transferContextAction = transferContextAction;
 window.previewDeviceImage = previewDeviceImage;
 window._isImageFile = _isImageFile;
+window._isLvglBinFile = _isLvglBinFile;
+window.convertLvglToPng = convertLvglToPng;
 window._isTextFile = _isTextFile;
 window._getAceMode = _getAceMode;
 window.openDeviceTextFile = openDeviceTextFile;

Tools/WebServer/static/js/locales/en.js

@@ -396,6 +396,8 @@ window.i18nResources['en'] = {
       unsaved_changes: 'File {{name}} has unsaved changes. Discard?',
       save_to_device: 'Save to device (Ctrl+S)',
       download_to_pc: 'Download to PC',
+      icu_not_installed:
+        'The "icu" tool is required to preview LVGL images but is not installed.\nOpen the installation page?',
     },
 
     // Device

Tools/WebServer/static/js/locales/zh-CN.js

@@ -388,6 +388,8 @@ window.i18nResources['zh-CN'] = {
       unsaved_changes: '文件 {{name}} 有未保存的修改，确定丢弃？',
       save_to_device: '保存到设备 (Ctrl+S)',
       download_to_pc: '下载到本地',
+      icu_not_installed:
+        '预览 LVGL 图片需要安装 "icu" 工具，当前未安装。\n是否打开安装页面？',
     },
 
     // 设备

Tools/WebServer/static/js/locales/zh-TW.js

@@ -389,6 +389,8 @@ window.i18nResources['zh-TW'] = {
       unsaved_changes: '檔案 {{name}} 有未儲存的修改，確定捨棄？',
       save_to_device: '儲存到裝置 (Ctrl+S)',
       download_to_pc: '下載到本機',
+      icu_not_installed:
+        '預覽 LVGL 圖片需要安裝 "icu" 工具，目前未安裝。\n是否開啟安裝頁面？',
     },
 
     // 裝置

Tools/WebServer/tests/js/test_transfer.js

@@ -2912,6 +2912,44 @@ module.exports = function (w) {
     });
   });
 
+  describe('LVGL Binary Image Functions', () => {
+    it('_isLvglBinFile recognizes .bin files', () =>
+      assertTrue(w._isLvglBinFile('image.bin')));
+    it('_isLvglBinFile is case insensitive', () =>
+      assertTrue(w._isLvglBinFile('IMAGE.BIN')));
+    it('_isLvglBinFile rejects .png files', () =>
+      assertFalse(w._isLvglBinFile('image.png')));
+    it('_isLvglBinFile rejects .txt files', () =>
+      assertFalse(w._isLvglBinFile('data.txt')));
+    it('convertLvglToPng is async function', () =>
+      assertTrue(w.convertLvglToPng.constructor.name === 'AsyncFunction'));
+
+    it('convertLvglToPng handles API error', async () => {
+      setFetchResponse('/api/convert/lvgl-to-png', {
+        success: false,
+        error: 'icu tool not installed',
+      });
+      const blob = new Blob([new Uint8Array([1, 2, 3])]);
+      const result = await w.convertLvglToPng(blob);
+      assertFalse(result.success);
+      assertTrue(result.error.includes('icu'));
+    });
+
+    it('convertLvglToPng returns PNG blob on success', async () => {
+      // Mock a successful conversion returning base64 PNG
+      const fakePng = btoa('fake png');
+      setFetchResponse('/api/convert/lvgl-to-png', {
+        success: true,
+        data: fakePng,
+        size: 8,
+      });
+      const blob = new Blob([new Uint8Array([1, 2, 3])]);
+      const result = await w.convertLvglToPng(blob);
+      assertTrue(result.success);
+      assertTrue(result.blob instanceof Blob);
+    });
+  });
+
   describe('closeTab dirty confirmation', () => {
     it('prompts confirm for dirty textfile tab', () => {
       const origConfirm = browserGlobals.confirm;

Tools/WebServer/tests/test_file_routes.py

@@ -2,6 +2,7 @@
 """Tests for app/routes/files.py"""
 
 import os
+import subprocess
 import sys
 import tempfile
 import unittest
@@ -307,5 +308,80 @@ def test_write_binary_watch_dir_parent_allowed(self):
         self.assertTrue(data["success"])
 
 
+class TestConvertLvglToPng(FileRoutesBase):
+    """Tests for /api/convert/lvgl-to-png endpoint."""
+
+    def test_no_data(self):
+        res = self.client.post("/api/convert/lvgl-to-png", json={})
+        data = res.get_json()
+        self.assertFalse(data["success"])
+        self.assertIn("No data", data["error"])
+
+    def test_empty_data(self):
+        res = self.client.post("/api/convert/lvgl-to-png", json={"data": ""})
+        data = res.get_json()
+        self.assertFalse(data["success"])
+
+    def test_invalid_base64(self):
+        res = self.client.post(
+            "/api/convert/lvgl-to-png", json={"data": "!!!invalid!!!"}
+        )
+        data = res.get_json()
+        self.assertFalse(data["success"])
+        self.assertIn("Invalid base64", data["error"])
+
+    @patch("shutil.which", return_value=None)
+    def test_icu_not_installed(self, mock_which):
+        import base64
+
+        b64 = base64.b64encode(b"\x00" * 10).decode()
+        res = self.client.post("/api/convert/lvgl-to-png", json={"data": b64})
+        data = res.get_json()
+        self.assertFalse(data["success"])
+        self.assertIn("icu tool not installed", data["error"])
+
+    @patch("subprocess.run")
+    @patch("shutil.which", return_value="/usr/bin/icu")
+    def test_conversion_failure(self, mock_which, mock_run):
+        import base64
+
+        mock_run.return_value = unittest.mock.Mock(
+            returncode=1, stdout=b"", stderr=b"Not a valid LVGL image"
+        )
+        b64 = base64.b64encode(b"\x00" * 10).decode()
+        res = self.client.post("/api/convert/lvgl-to-png", json={"data": b64})
+        data = res.get_json()
+        self.assertFalse(data["success"])
+
+    @patch("subprocess.run")
+    @patch("shutil.which", return_value="/usr/bin/icu")
+    def test_conversion_success(self, mock_which, mock_run):
+        import base64
+
+        fake_png = b"\x89PNG\r\n\x1a\nfake"
+        mock_run.return_value = unittest.mock.Mock(
+            returncode=0, stdout=fake_png, stderr=b""
+        )
+        b64 = base64.b64encode(b"\x00" * 10).decode()
+        res = self.client.post("/api/convert/lvgl-to-png", json={"data": b64})
+        data = res.get_json()
+        self.assertTrue(data["success"])
+        self.assertEqual(data["size"], len(fake_png))
+        # Verify returned data decodes to the fake PNG
+        decoded = base64.b64decode(data["data"])
+        self.assertEqual(decoded, fake_png)
+
+    @patch("subprocess.run", side_effect=subprocess.TimeoutExpired("icu", 10))
+    @patch("shutil.which", return_value="/usr/bin/icu")
+    def test_conversion_timeout(self, mock_which, mock_run):
+        import base64
+
+        b64 = base64.b64encode(b"\x00" * 10).decode()
+        res = self.client.post("/api/convert/lvgl-to-png", json={"data": b64})
+        data = res.get_json()
+        self.assertFalse(data["success"])
+        self.assertIn("timed out", data["error"])
+
+
 if __name__ == "__main__":
     unittest.main()

Tools/WebServer/tests/test_frontend.js

@@ -112,6 +112,8 @@ const globalFunctions = [
   'formatFileSize',
   'refreshTextFileTab',
   'refreshPreviewTab',
+  '_isLvglBinFile',
+  'convertLvglToPng',
   // Config schema functions
   'loadConfigSchema',
   'getConfigSchema',