feat: roll out app icon identity across platforms

Author: hieshima

DEVELOPMENT.md

@@ -319,7 +319,7 @@ pip install pyinstaller
 pyinstaller Mouser-linux.spec --noconfirm
 ```
 
-Output: `dist/Mouser/`. The release pipeline additionally bundles `69-mouser-logitech.rules` and `install-linux-permissions.sh`, runs `ldd` on the resulting binary to flag missing libraries, and performs an offscreen smoke test (`QT_QPA_PLATFORM=offscreen`).
+Output: `dist/Mouser/`. The release pipeline additionally bundles the Linux permission helper files and hicolor app-icon ladder, runs `ldd` on the resulting binary to flag missing libraries, and performs an offscreen smoke test (`QT_QPA_PLATFORM=offscreen`).
 
 ## Desktop shortcut (Windows)
 

Mouser-linux.spec

@@ -102,6 +102,10 @@ a = Analysis(
             os.path.join(ROOT, "packaging", "linux", "io.github.tombadash.mouser.desktop.in"),
             "linux",
         ),
+        (
+            os.path.join(ROOT, "packaging", "linux", "icons"),
+            os.path.join("linux", "icons"),
+        ),
         (BUILD_INFO_DATA, "."),
     ],
     hiddenimports=[

README.md

@@ -292,7 +292,7 @@ The first normal Linux launch creates or refreshes:
 ~/.local/share/applications/io.github.tombadash.mouser.desktop
 ```
 
-The generated launcher uses absolute paths for the current portable app or source checkout. If you move the checkout, launch Mouser once from the new path to refresh the app-menu entry. Enabling **Start at login** also manages:
+The generated launcher uses absolute paths for the current portable app or source checkout, and syncs Mouser's app icon into the per-user hicolor icon theme when possible. If you move the checkout, launch Mouser once from the new path to refresh the app-menu entry. Enabling **Start at login** also manages:
 
 ```text
 ~/.config/autostart/io.github.tombadash.mouser.desktop

core/startup.py

@@ -2,6 +2,7 @@
 
 import os
 import plistlib
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -15,9 +16,13 @@
 MACOS_PLIST_NAME = f"{MACOS_LAUNCH_AGENT_LABEL}.plist"
 
 # Linux
+LINUX_APP_ID = "io.github.tombadash.mouser"
 LINUX_DESKTOP_ENTRY_NAME = "io.github.tombadash.mouser.desktop"
 LINUX_DESKTOP_TEMPLATE_NAME = f"{LINUX_DESKTOP_ENTRY_NAME}.in"
 LINUX_AUTOSTART_DELAY_SECONDS = 15
+LINUX_ICON_NAME = LINUX_APP_ID
+LINUX_ICON_FILENAME = f"{LINUX_ICON_NAME}.png"
+LINUX_ICON_SIZES = (16, 24, 32, 48, 64, 128, 256, 512)
 APP_DISPLAY_NAME = "Mouser"
 
 
@@ -147,6 +152,84 @@ def _linux_icon_path() -> str:
     return os.path.join(_repo_root_dir(), "images", "logo_icon.png")
 
 
+def _linux_icon_theme_source_root() -> str:
+    candidates = []
+    if getattr(sys, "frozen", False):
+        bundle_root = getattr(sys, "_MEIPASS", "")
+        if bundle_root:
+            candidates.append(os.path.join(bundle_root, "linux", "icons", "hicolor"))
+        candidates.append(
+            os.path.join(_runtime_root_dir(), "linux", "icons", "hicolor")
+        )
+    candidates.append(
+        os.path.join(_repo_root_dir(), "packaging", "linux", "icons", "hicolor")
+    )
+    for candidate in candidates:
+        if os.path.isdir(candidate):
+            return candidate
+    return ""
+
+
+def _linux_user_icon_theme_root() -> str:
+    xdg_data_home = os.environ.get("XDG_DATA_HOME", "").strip()
+    data_home = (
+        os.path.expanduser(xdg_data_home)
+        if xdg_data_home
+        else os.path.expanduser(os.path.join("~", ".local", "share"))
+    )
+    return os.path.join(data_home, "icons", "hicolor")
+
+
+def _linux_icon_source_path(source_root: str, size: int) -> str:
+    return os.path.join(
+        source_root,
+        f"{size}x{size}",
+        "apps",
+        LINUX_ICON_FILENAME,
+    )
+
+
+def _linux_icon_destination_path(destination_root: str, size: int) -> str:
+    return os.path.join(
+        destination_root,
+        f"{size}x{size}",
+        "apps",
+        LINUX_ICON_FILENAME,
+    )
+
+
+def _sync_linux_icon_theme() -> bool:
+    source_root = _linux_icon_theme_source_root()
+    if not source_root:
+        return False
+    sources = [
+        _linux_icon_source_path(source_root, size)
+        for size in LINUX_ICON_SIZES
+    ]
+    if not all(os.path.isfile(source) for source in sources):
+        return False
+    destination_root = _linux_user_icon_theme_root()
+    try:
+        for size, source in zip(LINUX_ICON_SIZES, sources):
+            destination = _linux_icon_destination_path(destination_root, size)
+            os.makedirs(os.path.dirname(destination), exist_ok=True)
+            shutil.copyfile(source, destination)
+            try:
+                os.chmod(destination, 0o644)
+            except OSError:
+                pass
+    except OSError as exc:
+        print(f"[startup] failed to sync Linux icon theme: {exc}")
+        return False
+    return True
+
+
+def _linux_icon_name_or_path() -> str:
+    if _sync_linux_icon_theme():
+        return LINUX_ICON_NAME
+    return _linux_icon_path()
+
+
 def _linux_source_path() -> str:
     if getattr(sys, "frozen", False):
         return os.path.abspath(sys.executable)
@@ -177,7 +260,7 @@ def _render_linux_desktop_entry(*, autostart: bool) -> str:
         "@EXEC@": _desktop_exec_string(exec_parts),
         "@TRY_EXEC@": exec_parts[0],
         "@WORKDIR@": _runtime_root_dir(),
-        "@ICON@": _linux_icon_path(),
+        "@ICON@": _linux_icon_name_or_path(),
         "@SOURCE_PATH@": _linux_source_path(),
         "@AUTOSTART_LINES@": autostart_lines,
     }

main_qml.py

@@ -47,7 +47,7 @@ def _resolve_root_dir():
 
 _t1 = _time.perf_counter()
 from PySide6.QtWidgets import QApplication, QSystemTrayIcon, QMenu, QFileIconProvider, QMessageBox
-from PySide6.QtGui import QAction, QColor, QIcon, QPainter, QPixmap, QWindow
+from PySide6.QtGui import QAction, QColor, QGuiApplication, QIcon, QPainter, QPixmap, QWindow
 from PySide6.QtCore import QObject, Property, QCoreApplication, QRectF, Qt, QUrl, Signal, QFileInfo, QEvent, QTimer
 from PySide6.QtQml import QQmlApplicationEngine
 from PySide6.QtQuick import QQuickImageProvider
@@ -78,6 +78,10 @@ def _print_startup_times():
     print(f"[Startup] Total imports:    {(_t4-_t0)*1000:7.1f} ms")
 
 
+LINUX_DESKTOP_FILE_BASENAME = "io.github.tombadash.mouser"
+WINDOWS_APP_USER_MODEL_ID = "TomBadash.Mouser"
+
+
 def _parse_cli_args(argv):
     qt_argv = [argv[0]]
     hid_backend = None
@@ -168,7 +172,10 @@ def _app_icon() -> QIcon:
     pixmap path produced. Logs and returns an empty QIcon if the asset
     file is missing.
     """
-    icon_name = "logo_icon.png" if sys.platform == "darwin" else "logo.ico"
+    if sys.platform == "win32":
+        icon_name = "logo.ico"
+    else:
+        icon_name = "logo_icon.png"
     icon_path = os.path.join(ROOT, "images", icon_name)
     if not os.path.isfile(icon_path):
         print(f"[Mouser] App icon missing: {icon_path}")
@@ -218,6 +225,35 @@ def _tray_icon() -> QIcon:
     return icon
 
 
+def _configure_windows_app_user_model_id() -> None:
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        set_app_id = ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID
+        set_app_id.argtypes = [wintypes.LPCWSTR]
+        set_app_id.restype = getattr(wintypes, "HRESULT", ctypes.c_long)
+        result = int(set_app_id(WINDOWS_APP_USER_MODEL_ID))
+        if result != 0:
+            print(
+                "[Mouser] Failed to set Windows AppUserModelID: "
+                f"0x{result & 0xFFFFFFFF:08X}"
+            )
+    except Exception as exc:
+        print(f"[Mouser] Failed to set Windows AppUserModelID: {exc}")
+
+
+def _configure_linux_desktop_file_name(app: QGuiApplication) -> None:
+    if sys.platform != "linux":
+        return
+    try:
+        app.setDesktopFileName(LINUX_DESKTOP_FILE_BASENAME)
+    except Exception as exc:
+        print(f"[Mouser] Failed to set Linux desktop file name: {exc}")
+
+
 _MACOS_RELAUNCH_GUARD = "MOUSER_MACOS_RELAUNCHED"
 
 
@@ -595,6 +631,16 @@ def _install_macos_dock_icon():
         print(f"[Mouser] Failed to apply macOS Dock icon: {exc}")
 
 
+def _schedule_macos_dock_icon_refresh() -> None:
+    if sys.platform != "darwin":
+        return
+    try:
+        QTimer.singleShot(0, _install_macos_dock_icon)
+        QTimer.singleShot(250, _install_macos_dock_icon)
+    except Exception:
+        _install_macos_dock_icon()
+
+
 def _set_macos_activation_policy(regular: bool) -> None:
     """Toggle between the Regular (foreground, Dock + Cmd+Tab) and
     Accessory (menu-bar only) policies. On a Regular promotion AppKit
@@ -608,6 +654,8 @@ def _set_macos_activation_policy(regular: bool) -> None:
     if sys.platform != "darwin":
         return
     if _MACOS_ACTIVATION_POLICY_REGULAR == regular:
+        if regular:
+            _schedule_macos_dock_icon_refresh()
         return
     appkit = _macos_appkit()
     if appkit is None:
@@ -624,6 +672,7 @@ def _set_macos_activation_policy(regular: bool) -> None:
     _MACOS_ACTIVATION_POLICY_REGULAR = regular
     if regular:
         _install_macos_dock_icon()
+        _schedule_macos_dock_icon_refresh()
 
 
 def _activate_macos_window():
@@ -965,12 +1014,14 @@ def main():
     # surfaces that read from `[NSBundle mainBundle]` (application menu
     # first item, Force Quit, notification banners) say "Mouser" too.
     _rename_macos_bundle_for_dock()
+    _configure_windows_app_user_model_id()
 
     QCoreApplication.setAttribute(Qt.ApplicationAttribute.AA_ShareOpenGLContexts)
     app = QApplication(argv)
     app.setApplicationName("Mouser")
     app.setApplicationVersion(APP_VERSION)
     app.setOrganizationName("Mouser")
+    _configure_linux_desktop_file_name(app)
     app.setWindowIcon(_app_icon())
     app.setQuitOnLastWindowClosed(False)
     _configure_macos_app_mode()
@@ -1088,6 +1139,7 @@ def show_main_window():
         root_window.showNormal()
         root_window.raise_()
         root_window.requestActivate()
+        _schedule_macos_dock_icon_refresh()
         _activate_macos_window()
 
     def _on_window_visibility_changed(visibility):