feat: add system tray and __main__ entry point

Add pystray-based system tray icon with Open UI / Restart / Quit
actions. Add __main__.py for `python -m wled_controller` support.
Update start-hidden.vbs with embedded Python fallback for both
installed and dev environments.

server/pyproject.toml

@@ -75,6 +75,9 @@ perf = [
     "bettercam>=1.0.0; sys_platform == 'win32'",
     "windows-capture>=1.5.0; sys_platform == 'win32'",
 ]
+tray = [
+    "pystray>=0.19.0; sys_platform == 'win32'",
+]
 
 [project.urls]
 Homepage = "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"

server/restart.ps1

@@ -1,7 +1,7 @@
 # Restart the WLED Screen Controller server
 # Stop any running instance
 $procs = Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
-    Where-Object { $_.CommandLine -like '*wled_controller.main*' }
+    Where-Object { $_.CommandLine -like '*wled_controller*' -and $_.CommandLine -notlike '*demo*' -and $_.CommandLine -notlike '*vscode*' -and $_.CommandLine -notlike '*isort*' }
 foreach ($p in $procs) {
     Write-Host "Stopping server (PID $($p.ProcessId))..."
     Stop-Process -Id $p.ProcessId -Force -ErrorAction SilentlyContinue
@@ -21,7 +21,12 @@ if ($regUser) {
 
 # Start server detached
 Write-Host "Starting server..."
-Start-Process -FilePath python -ArgumentList '-m', 'wled_controller.main' `
+$pythonExe = (Get-Command python -ErrorAction SilentlyContinue).Source
+if (-not $pythonExe) {
+    # Fallback to known install location
+    $pythonExe = "$env:LOCALAPPDATA\Programs\Python\Python313\python.exe"
+}
+Start-Process -FilePath $pythonExe -ArgumentList '-m', 'wled_controller' `
     -WorkingDirectory 'c:\Users\Alexei\Documents\wled-screen-controller\server' `
     -WindowStyle Hidden
 
@@ -29,7 +34,7 @@ Start-Sleep -Seconds 3
 
 # Verify it's running
 $check = Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
-    Where-Object { $_.CommandLine -like '*wled_controller.main*' }
+    Where-Object { $_.CommandLine -like '*wled_controller*' -and $_.CommandLine -notlike '*demo*' -and $_.CommandLine -notlike '*vscode*' -and $_.CommandLine -notlike '*isort*' }
 if ($check) {
     Write-Host "Server started (PID $($check[0].ProcessId))"
 } else {

server/scripts/restart-server.bat

@@ -18,7 +18,7 @@ cd /d "%~dp0\.."
 REM Start the server
 echo.
 echo [2/2] Starting server...
-python -m uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
+python -m wled_controller
 
 REM If the server exits, pause to show any error messages
 pause

server/scripts/start-hidden.vbs

@@ -0,0 +1,13 @@
+Set fso = CreateObject("Scripting.FileSystemObject")
+Set WshShell = CreateObject("WScript.Shell")
+' Get the directory of this script (scripts\), then go up to app root
+scriptDir = fso.GetParentFolderName(WScript.ScriptFullName)
+appRoot = fso.GetParentFolderName(scriptDir)
+WshShell.CurrentDirectory = appRoot
+' Use embedded Python if present (installed dist), otherwise system Python
+embeddedPython = appRoot & "\python\pythonw.exe"
+If fso.FileExists(embeddedPython) Then
+    WshShell.Run """" & embeddedPython & """ -m wled_controller", 0, False
+Else
+    WshShell.Run "python -m wled_controller", 0, False
+End If

server/scripts/start-server-background.vbs

@@ -2,6 +2,6 @@ Set WshShell = CreateObject("WScript.Shell")
 Set FSO = CreateObject("Scripting.FileSystemObject")
 ' Get parent folder of scripts folder (server root)
 WshShell.CurrentDirectory = FSO.GetParentFolderName(FSO.GetParentFolderName(WScript.ScriptFullName))
-WshShell.Run "python -m uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080", 0, False
+WshShell.Run "python -m wled_controller", 0, False
 Set FSO = Nothing
 Set WshShell = Nothing

server/scripts/start-server.bat

@@ -9,7 +9,7 @@ REM Change to the server directory (parent of scripts folder)
 cd /d "%~dp0\.."
 
 REM Start the server
-python -m uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
+python -m wled_controller
 
 REM If the server exits, pause to show any error messages
 pause

server/src/wled_controller/__main__.py

@@ -0,0 +1,101 @@
+"""Entry point for ``python -m wled_controller``.
+
+Starts the uvicorn server and, on Windows when *pystray* is installed,
+shows a system-tray icon with **Show UI** / **Exit** actions.
+"""
+
+import asyncio
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from wled_controller.config import get_config
+from wled_controller.tray import PYSTRAY_AVAILABLE, TrayManager
+from wled_controller.utils import setup_logging, get_logger
+
+setup_logging()
+logger = get_logger(__name__)
+
+_ICON_PATH = Path(__file__).parent / "static" / "icons" / "icon-192.png"
+
+
+def _run_server(server: uvicorn.Server) -> None:
+    """Run uvicorn in a dedicated asyncio event loop (background thread)."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    loop.run_until_complete(server.serve())
+
+
+def _open_browser(port: int, delay: float = 2.0) -> None:
+    """Open the UI in the default browser after a short delay."""
+    time.sleep(delay)
+    webbrowser.open(f"http://localhost:{port}")
+
+
+def main() -> None:
+    config = get_config()
+
+    uv_config = uvicorn.Config(
+        "wled_controller.main:app",
+        host=config.server.host,
+        port=config.server.port,
+        log_level=config.server.log_level.lower(),
+    )
+    server = uvicorn.Server(uv_config)
+
+    use_tray = PYSTRAY_AVAILABLE and (
+        sys.platform == "win32" or _force_tray()
+    )
+
+    if use_tray:
+        logger.info("Starting with system tray icon")
+
+        # Uvicorn in a background thread
+        server_thread = threading.Thread(
+            target=_run_server, args=(server,), daemon=True,
+        )
+        server_thread.start()
+
+        # Browser after a short delay
+        threading.Thread(
+            target=_open_browser,
+            args=(config.server.port,),
+            daemon=True,
+        ).start()
+
+        # Tray on main thread (blocking)
+        tray = TrayManager(
+            icon_path=_ICON_PATH,
+            port=config.server.port,
+            on_exit=lambda: _request_shutdown(server),
+        )
+        tray.run()
+
+        # Tray exited — wait for server to finish its graceful shutdown
+        server_thread.join(timeout=10)
+    else:
+        if not PYSTRAY_AVAILABLE:
+            logger.info(
+                "System tray not available (install pystray for tray support)"
+            )
+        server.run()
+
+
+def _request_shutdown(server: uvicorn.Server) -> None:
+    """Signal uvicorn to perform a graceful shutdown."""
+    server.should_exit = True
+
+
+def _force_tray() -> bool:
+    """Allow forcing tray on non-Windows via WLED_TRAY=1."""
+    import os
+
+    return os.environ.get("WLED_TRAY", "").strip() in ("1", "true", "yes")
+
+
+if __name__ == "__main__":
+    main()

server/src/wled_controller/main.py

@@ -32,6 +32,7 @@ from wled_controller.storage.automation_store import AutomationStore
 from wled_controller.storage.scene_preset_store import ScenePresetStore
 from wled_controller.storage.sync_clock_store import SyncClockStore
 from wled_controller.storage.color_strip_processing_template_store import ColorStripProcessingTemplateStore
+from wled_controller.storage.gradient_store import GradientStore
 from wled_controller.core.processing.sync_clock_manager import SyncClockManager
 from wled_controller.core.automations.automation_engine import AutomationEngine
 from wled_controller.core.mqtt.mqtt_service import MQTTService
@@ -69,6 +70,8 @@ automation_store = AutomationStore(config.storage.automations_file)
 scene_preset_store = ScenePresetStore(config.storage.scene_presets_file)
 sync_clock_store = SyncClockStore(config.storage.sync_clocks_file)
 cspt_store = ColorStripProcessingTemplateStore(config.storage.color_strip_processing_templates_file)
+gradient_store = GradientStore(config.storage.gradients_file)
+gradient_store.migrate_palette_references(color_strip_store)
 sync_clock_manager = SyncClockManager(sync_clock_store)
 
 processor_manager = ProcessorManager(
@@ -84,6 +87,7 @@ processor_manager = ProcessorManager(
         audio_template_store=audio_template_store,
         sync_clock_manager=sync_clock_manager,
         cspt_store=cspt_store,
+        gradient_store=gradient_store,
     )
 )
 
@@ -167,6 +171,7 @@ async def lifespan(app: FastAPI):
         sync_clock_store=sync_clock_store,
         sync_clock_manager=sync_clock_manager,
         cspt_store=cspt_store,
+        gradient_store=gradient_store,
     )
 
     # Register devices in processor manager for health monitoring

server/src/wled_controller/tray.py

@@ -0,0 +1,71 @@
+"""System tray icon for LED Grab (Windows)."""
+
+import webbrowser
+from pathlib import Path
+from typing import Callable
+
+from PIL import Image
+
+try:
+    import pystray
+
+    PYSTRAY_AVAILABLE = True
+except ImportError:
+    PYSTRAY_AVAILABLE = False
+
+
+def _load_icon(icon_path: Path) -> Image.Image:
+    """Load tray icon from PNG, with a solid-color fallback."""
+    if icon_path.exists():
+        return Image.open(icon_path)
+    # Fallback: blue square
+    return Image.new("RGB", (64, 64), (0, 120, 255))
+
+
+class TrayManager:
+    """Manages the system tray icon and its context menu.
+
+    Call ``run()`` on the **main thread** — it blocks until ``stop()``
+    is called (from any thread) or the user picks *Exit* from the menu.
+    """
+
+    def __init__(self, icon_path: Path, port: int, on_exit: Callable[[], None]) -> None:
+        if not PYSTRAY_AVAILABLE:
+            raise ImportError("pystray is required for system tray support")
+
+        self._port = port
+        self._on_exit = on_exit
+
+        image = _load_icon(icon_path)
+
+        menu = pystray.Menu(
+            pystray.MenuItem("Show UI", self._show_ui, default=True),
+            pystray.Menu.SEPARATOR,
+            pystray.MenuItem("Exit", self._exit),
+        )
+
+        self._icon = pystray.Icon(
+            name="ledgrab",
+            icon=image,
+            title="LED Grab",
+            menu=menu,
+        )
+
+    # -- menu callbacks ------------------------------------------------
+
+    def _show_ui(self, icon: "pystray.Icon", item: "pystray.MenuItem") -> None:
+        webbrowser.open(f"http://localhost:{self._port}")
+
+    def _exit(self, icon: "pystray.Icon", item: "pystray.MenuItem") -> None:
+        self._on_exit()
+        self._icon.stop()
+
+    # -- public API ----------------------------------------------------
+
+    def run(self) -> None:
+        """Block the calling thread running the tray message loop."""
+        self._icon.run()
+
+    def stop(self) -> None:
+        """Stop the tray icon from any thread."""
+        self._icon.stop()