perf: pre-compile Python bytecode in portable build

Add compileall step to build-dist-windows.sh that generates .pyc files for both app source and site-packages. Saves ~100-200ms on startup by skipping parse/compile on first import.
perf: reduce portable build size ~40MB — replace winsdk/wmi, migrate cv2 to Pillow
2026-03-22 13:38:15 +03:00 · 2026-03-22 13:35:01 +03:00 · 2026-03-22 03:49:55 +03:00 · 2026-03-22 03:46:20 +03:00 · 2026-03-22 03:44:37 +03:00 · 2026-03-22 03:40:06 +03:00
19 changed files with 1282 additions and 115 deletions
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -6,69 +6,222 @@ on:
      - 'v*'

 jobs:
+  # ── Create the release first (shared by all build jobs) ────
+  create-release:
+    runs-on: ubuntu-latest
+    outputs:
+      release_id: ${{ steps.create.outputs.release_id }}
+    steps:
+      - name: Create Gitea release
+        id: create
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          IS_PRE="false"
+          if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            IS_PRE="true"
+          fi
+
+          RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "{
+              \"tag_name\": \"$TAG\",
+              \"name\": \"LedGrab $TAG\",
+              \"body\": \"## Downloads\\n\\n| Platform | File | How to run |\\n|----------|------|------------|\\n| Windows | \`LedGrab-${TAG}-win-x64.zip\` | Unzip → run \`LedGrab.bat\` → open http://localhost:8080 |\\n| Linux | \`LedGrab-${TAG}-linux-x64.tar.gz\` | Extract → run \`./run.sh\` → open http://localhost:8080 |\\n| Docker | See below | \`docker pull\` → \`docker run\` |\\n\\n### Docker\\n\\n\`\`\`bash\\ndocker pull ${{ gitea.server_url }}/${{ gitea.repository }}:${TAG}\\ndocker run -d -p 8080:8080 ${{ gitea.server_url }}/${{ gitea.repository }}:${TAG}\\n\`\`\`\",
+              \"draft\": false,
+              \"prerelease\": $IS_PRE
+            }")
+
+          RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+          echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
+          echo "Created release ID: $RELEASE_ID"
+
+  # ── Windows portable ZIP (cross-built from Linux) ─────────
  build-windows:
-    runs-on: windows-latest
+    needs: create-release
+    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

-      - name: Build portable distribution
-        shell: pwsh
+      - name: Install system dependencies
        run: |
-          .\build-dist.ps1 -Version "${{ gitea.ref_name }}"
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends zip libportaudio2 nsis msitools
+
+      - name: Cross-build Windows distribution
+        run: |
+          chmod +x build-dist-windows.sh
+          ./build-dist-windows.sh "${{ gitea.ref_name }}"
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: LedGrab-${{ gitea.ref_name }}-win-x64
+          path: |
+            build/LedGrab-*.zip
+            build/LedGrab-*-setup.exe
+          retention-days: 90
+
+      - name: Attach assets to release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          # Upload ZIP
+          ZIP_FILE=$(ls build/LedGrab-*.zip | head -1)
+          if [ -f "$ZIP_FILE" ]; then
+            curl -s -X POST \
+              "$BASE_URL/releases/$RELEASE_ID/assets?name=$(basename "$ZIP_FILE")" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@$ZIP_FILE"
+            echo "Uploaded: $(basename "$ZIP_FILE")"
+          fi
+
+          # Upload installer
+          SETUP_FILE=$(ls build/LedGrab-*-setup.exe 2>/dev/null | head -1)
+          if [ -f "$SETUP_FILE" ]; then
+            curl -s -X POST \
+              "$BASE_URL/releases/$RELEASE_ID/assets?name=$(basename "$SETUP_FILE")" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@$SETUP_FILE"
+            echo "Uploaded: $(basename "$SETUP_FILE")"
+          fi
+
+  # ── Linux tarball ──────────────────────────────────────────
+  build-linux:
+    needs: create-release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libportaudio2
+
+      - name: Build Linux distribution
+        run: |
+          chmod +x build-dist.sh
+          ./build-dist.sh "${{ gitea.ref_name }}"

      - name: Upload build artifact
        uses: actions/upload-artifact@v3
        with:
-          name: LedGrab-${{ gitea.ref_name }}-win-x64
-          path: build/LedGrab-*.zip
+          name: LedGrab-${{ gitea.ref_name }}-linux-x64
+          path: build/LedGrab-*.tar.gz
          retention-days: 90

-      - name: Create Gitea release
-        shell: pwsh
+      - name: Attach tarball to release
        env:
          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
        run: |
-          $tag = "${{ gitea.ref_name }}"
-          $zipFile = Get-ChildItem "build\LedGrab-*.zip" | Select-Object -First 1
-          if (-not $zipFile) { throw "ZIP not found" }
+          TAG="${{ gitea.ref_name }}"
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+          TAR_FILE=$(ls build/LedGrab-*.tar.gz | head -1)
+          TAR_NAME=$(basename "$TAR_FILE")

-          $baseUrl = "${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
-          $headers = @{
-            "Authorization" = "token $env:GITEA_TOKEN"
-            "Content-Type"  = "application/json"
-          }
+          curl -s -X POST \
+            "$BASE_URL/releases/$RELEASE_ID/assets?name=$TAR_NAME" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@$TAR_FILE"

-          # Create release
-          $body = @{
-            tag_name   = $tag
-            name       = "LedGrab $tag"
-            body       = "Portable Windows build — unzip, run ``LedGrab.bat``, open http://localhost:8080"
-            draft      = $false
-            prerelease = ($tag -match '(alpha|beta|rc)')
-          } | ConvertTo-Json
+          echo "Uploaded: $TAR_NAME"

-          $release = Invoke-RestMethod -Method Post `
-            -Uri "$baseUrl/releases" `
-            -Headers $headers -Body $body
+  # ── Docker image ───────────────────────────────────────────
+  build-docker:
+    needs: create-release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0

-          Write-Host "Created release: $($release.html_url)"
+      - name: Extract version metadata
+        id: meta
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          VERSION="${TAG#v}"
+          # Strip protocol and lowercase for Docker registry path
+          SERVER_HOST=$(echo "${{ gitea.server_url }}" | sed -E 's|https?://||')
+          REPO=$(echo "${{ gitea.repository }}" | tr '[:upper:]' '[:lower:]')
+          REGISTRY="${SERVER_HOST}/${REPO}"

-          # Upload ZIP asset
-          $uploadHeaders = @{
-            "Authorization" = "token $env:GITEA_TOKEN"
-          }
-          $uploadUrl = "$baseUrl/releases/$($release.id)/assets?name=$($zipFile.Name)"
-          Invoke-RestMethod -Method Post -Uri $uploadUrl `
-            -Headers $uploadHeaders `
-            -ContentType "application/octet-stream" `
-            -InFile $zipFile.FullName
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "registry=$REGISTRY" >> "$GITHUB_OUTPUT"
+          echo "server_host=$SERVER_HOST" >> "$GITHUB_OUTPUT"

-          Write-Host "Uploaded: $($zipFile.Name)"
+      - name: Login to Gitea Container Registry
+        id: docker-login
+        continue-on-error: true
+        run: |
+          echo "${{ secrets.GITEA_TOKEN }}" | docker login \
+            "${{ steps.meta.outputs.server_host }}" \
+            -u "${{ gitea.actor }}" --password-stdin
+
+      - name: Build Docker image
+        if: steps.docker-login.outcome == 'success'
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          REGISTRY="${{ steps.meta.outputs.registry }}"
+
+          docker build \
+            --label "org.opencontainers.image.version=${{ steps.meta.outputs.version }}" \
+            --label "org.opencontainers.image.revision=${{ gitea.sha }}" \
+            -t "$REGISTRY:$TAG" \
+            -t "$REGISTRY:${{ steps.meta.outputs.version }}" \
+            ./server
+
+          # Tag as latest only for stable releases
+          if ! echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            docker tag "$REGISTRY:$TAG" "$REGISTRY:latest"
+          fi
+
+      - name: Push Docker image
+        if: steps.docker-login.outcome == 'success'
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          REGISTRY="${{ steps.meta.outputs.registry }}"
+
+          docker push "$REGISTRY:$TAG"
+          docker push "$REGISTRY:${{ steps.meta.outputs.version }}"
+
+          if ! echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            docker push "$REGISTRY:latest"
+          fi
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -48,6 +48,21 @@ Use `TODO.md` in the project root as the primary task tracker. **Do NOT use the

 **Use context7 MCP tools for library/framework documentation lookups** (FastAPI, OpenCV, Pydantic, yt-dlp, etc.) instead of relying on potentially outdated training data.

+## Data Migration Policy (CRITICAL)
+
+**NEVER rename a storage file path, store key, entity ID prefix, or JSON field name without writing a migration.** User data lives in JSON files under `data/`. If the code starts reading from a new filename while the old file still has user data, THAT DATA IS SILENTLY LOST.
+
+When renaming any storage-related identifier:
+1. **Add migration logic in `BaseJsonStore.__init__`** (or the specific store) that detects the old file/key and migrates data to the new name automatically on startup
+2. **Log a clear warning** when migration happens so the user knows
+3. **Keep the old file as a backup** after migration (rename to `.migrated` or similar)
+4. **Test the migration** with both old-format and new-format data files
+5. **Document the migration** in the commit message
+
+This applies to: file paths in `StorageConfig`, JSON root keys (e.g. `picture_targets` → `output_targets`), entity ID prefixes (e.g. `pt_` → `ot_`), and any field renames in dataclass models.
+
+**Incident context:** A past rename of `picture_targets.json` → `output_targets.json` was done without migration. The app created a new empty `output_targets.json` while the user's 7 targets sat unread in the old file. Data was silently lost.
+
 ## General Guidelines

 - Always test changes before marking as complete
--- a/build-dist-windows.sh
+++ b/build-dist-windows.sh
@@ -0,0 +1,473 @@
+#!/usr/bin/env bash
+#
+# Cross-build a portable Windows distribution of LedGrab from Linux.
+#
+# Downloads Windows embedded Python and win_amd64 wheels — no Wine or
+# Windows runner needed. Produces the same ZIP as build-dist.ps1.
+#
+# Usage:
+#   ./build-dist-windows.sh [VERSION]
+#   ./build-dist-windows.sh v0.1.0-alpha.1
+#
+# Requirements: python3, pip, curl, unzip, zip, node/npm
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BUILD_DIR="$SCRIPT_DIR/build"
+DIST_NAME="LedGrab"
+DIST_DIR="$BUILD_DIR/$DIST_NAME"
+SERVER_DIR="$SCRIPT_DIR/server"
+PYTHON_DIR="$DIST_DIR/python"
+APP_DIR="$DIST_DIR/app"
+PYTHON_VERSION="${PYTHON_VERSION:-3.11.9}"
+
+# ── Version detection ────────────────────────────────────────
+
+VERSION="${1:-}"
+
+if [ -z "$VERSION" ]; then
+    VERSION=$(git describe --tags --exact-match 2>/dev/null || true)
+fi
+if [ -z "$VERSION" ]; then
+    VERSION="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+fi
+if [ -z "$VERSION" ]; then
+    VERSION=$(grep -oP '__version__\s*=\s*"\K[^"]+' "$SERVER_DIR/src/wled_controller/__init__.py" 2>/dev/null || echo "0.0.0")
+fi
+
+VERSION_CLEAN="${VERSION#v}"
+ZIP_NAME="LedGrab-v${VERSION_CLEAN}-win-x64.zip"
+
+echo "=== Cross-building LedGrab v${VERSION_CLEAN} (Windows from Linux) ==="
+echo "  Embedded Python: $PYTHON_VERSION"
+echo "  Output: build/$ZIP_NAME"
+echo ""
+
+# ── Clean ────────────────────────────────────────────────────
+
+if [ -d "$DIST_DIR" ]; then
+    echo "[1/9] Cleaning previous build..."
+    rm -rf "$DIST_DIR"
+fi
+mkdir -p "$DIST_DIR"
+
+# ── Download Windows embedded Python ─────────────────────────
+
+PYTHON_ZIP_URL="https://www.python.org/ftp/python/${PYTHON_VERSION}/python-${PYTHON_VERSION}-embed-amd64.zip"
+PYTHON_ZIP_PATH="$BUILD_DIR/python-embed-win.zip"
+
+echo "[2/9] Downloading Windows embedded Python ${PYTHON_VERSION}..."
+if [ ! -f "$PYTHON_ZIP_PATH" ]; then
+    curl -sL "$PYTHON_ZIP_URL" -o "$PYTHON_ZIP_PATH"
+fi
+mkdir -p "$PYTHON_DIR"
+unzip -qo "$PYTHON_ZIP_PATH" -d "$PYTHON_DIR"
+
+# ── Patch ._pth to enable site-packages ──────────────────────
+
+echo "[3/9] Patching Python path configuration..."
+PTH_FILE=$(ls "$PYTHON_DIR"/python*._pth 2>/dev/null | head -1)
+if [ -z "$PTH_FILE" ]; then
+    echo "ERROR: Could not find python*._pth in $PYTHON_DIR" >&2
+    exit 1
+fi
+
+# Uncomment 'import site', add Lib\site-packages and app source path
+sed -i 's/^#\s*import site/import site/' "$PTH_FILE"
+if ! grep -q 'Lib\\site-packages' "$PTH_FILE"; then
+    echo 'Lib\site-packages' >> "$PTH_FILE"
+fi
+# Embedded Python ._pth overrides PYTHONPATH, so we must add the app
+# source directory here for wled_controller to be importable
+if ! grep -q '\.\./app/src' "$PTH_FILE"; then
+    echo '../app/src' >> "$PTH_FILE"
+fi
+echo "  Patched $(basename "$PTH_FILE")"
+
+# ── Bundle tkinter into embedded Python ───────────────────────
+# Embedded Python doesn't include tkinter. We download the individual
+# MSI packages from python.org (tcltk.msi + lib.msi) and extract them
+# using msiextract (from msitools).
+
+echo "[4/9] Bundling tkinter for screen overlay support..."
+
+TK_EXTRACT="$BUILD_DIR/tk-extract"
+rm -rf "$TK_EXTRACT"
+mkdir -p "$TK_EXTRACT"
+
+MSI_BASE="https://www.python.org/ftp/python/${PYTHON_VERSION}/amd64"
+
+# Download tcltk.msi (contains _tkinter.pyd, tcl/tk DLLs, tcl8.6/, tk8.6/)
+TCLTK_MSI="$BUILD_DIR/tcltk.msi"
+if [ ! -f "$TCLTK_MSI" ]; then
+    curl -sL "$MSI_BASE/tcltk.msi" -o "$TCLTK_MSI"
+fi
+
+# Download lib.msi (contains tkinter/ Python package in the stdlib)
+LIB_MSI="$BUILD_DIR/lib.msi"
+if [ ! -f "$LIB_MSI" ]; then
+    curl -sL "$MSI_BASE/lib.msi" -o "$LIB_MSI"
+fi
+
+if command -v msiextract &>/dev/null; then
+    # Extract both MSIs
+    (cd "$TK_EXTRACT" && msiextract "$TCLTK_MSI" 2>/dev/null)
+    (cd "$TK_EXTRACT" && msiextract "$LIB_MSI" 2>/dev/null)
+
+    # Copy _tkinter.pyd
+    TKINTER_PYD=$(find "$TK_EXTRACT" -name "_tkinter.pyd" 2>/dev/null | head -1)
+    if [ -n "$TKINTER_PYD" ]; then
+        cp "$TKINTER_PYD" "$PYTHON_DIR/"
+        echo "  Copied _tkinter.pyd"
+    else
+        echo "  WARNING: _tkinter.pyd not found in tcltk.msi"
+    fi
+
+    # Copy Tcl/Tk DLLs
+    for dll in tcl86t.dll tk86t.dll; do
+        DLL_PATH=$(find "$TK_EXTRACT" -name "$dll" 2>/dev/null | head -1)
+        if [ -n "$DLL_PATH" ]; then
+            cp "$DLL_PATH" "$PYTHON_DIR/"
+            echo "  Copied $dll"
+        fi
+    done
+
+    # Copy tkinter Python package
+    TKINTER_PKG=$(find "$TK_EXTRACT" -type d -name "tkinter" 2>/dev/null | head -1)
+    if [ -n "$TKINTER_PKG" ]; then
+        mkdir -p "$PYTHON_DIR/Lib"
+        cp -r "$TKINTER_PKG" "$PYTHON_DIR/Lib/tkinter"
+        echo "  Copied tkinter/ package"
+    fi
+
+    # Copy tcl/tk data directories
+    for tcldir in tcl8.6 tk8.6; do
+        TCL_PATH=$(find "$TK_EXTRACT" -type d -name "$tcldir" 2>/dev/null | head -1)
+        if [ -n "$TCL_PATH" ]; then
+            cp -r "$TCL_PATH" "$PYTHON_DIR/$tcldir"
+            echo "  Copied $tcldir/"
+        fi
+    done
+
+    echo "  tkinter bundled successfully"
+else
+    echo "  WARNING: msiextract not found — skipping tkinter (install msitools)"
+fi
+
+# Add Lib to ._pth so tkinter package is importable
+if ! grep -q '^Lib$' "$PTH_FILE"; then
+    echo 'Lib' >> "$PTH_FILE"
+fi
+
+rm -rf "$TK_EXTRACT"
+
+# ── Download pip and install into embedded Python ────────────
+
+echo "[5/9] Installing pip into embedded Python..."
+SITE_PACKAGES="$PYTHON_DIR/Lib/site-packages"
+mkdir -p "$SITE_PACKAGES"
+
+# Download pip + setuptools wheels for Windows
+pip download --quiet --dest "$BUILD_DIR/pip-wheels" \
+    --platform win_amd64 --python-version "3.11" \
+    --implementation cp --only-binary :all: \
+    pip setuptools 2>/dev/null || \
+pip download --quiet --dest "$BUILD_DIR/pip-wheels" \
+    pip setuptools
+
+# Unzip pip into site-packages (we just need it to exist, not to run)
+for whl in "$BUILD_DIR/pip-wheels"/pip-*.whl; do
+    unzip -qo "$whl" -d "$SITE_PACKAGES"
+done
+for whl in "$BUILD_DIR/pip-wheels"/setuptools-*.whl; do
+    unzip -qo "$whl" -d "$SITE_PACKAGES"
+done
+
+# ── Download Windows wheels for all dependencies ─────────────
+
+echo "[6/9] Downloading Windows dependencies..."
+WHEEL_DIR="$BUILD_DIR/win-wheels"
+mkdir -p "$WHEEL_DIR"
+
+# Core dependencies (cross-platform, should have win_amd64 wheels)
+# We parse pyproject.toml deps and download win_amd64 wheels.
+# For packages that are pure Python, --only-binary will fail,
+# so we fall back to allowing source for those.
+DEPS=(
+    "fastapi>=0.115.0"
+    "uvicorn[standard]>=0.32.0"
+    "httpx>=0.27.2"
+    "mss>=9.0.2"
+    "Pillow>=10.4.0"
+    "numpy>=2.1.3"
+    "pydantic>=2.9.2"
+    "pydantic-settings>=2.6.0"
+    "PyYAML>=6.0.2"
+    "structlog>=24.4.0"
+    "python-json-logger>=3.1.0"
+    "python-dateutil>=2.9.0"
+    "python-multipart>=0.0.12"
+    "jinja2>=3.1.0"
+    "zeroconf>=0.131.0"
+    "pyserial>=3.5"
+    "psutil>=5.9.0"
+    "nvidia-ml-py>=12.0.0"
+    "sounddevice>=0.5"
+    "aiomqtt>=2.0.0"
+    "openrgb-python>=0.2.15"
+    # camera extra
+    "opencv-python-headless>=4.8.0"
+)
+
+# Windows-only deps
+WIN_DEPS=(
+    "PyAudioWPatch>=0.2.12"
+    "winrt-Windows.UI.Notifications>=3.0.0"
+    "winrt-Windows.UI.Notifications.Management>=3.0.0"
+    "winrt-Windows.Foundation>=3.0.0"
+    "winrt-Windows.Foundation.Collections>=3.0.0"
+    "winrt-Windows.ApplicationModel>=3.0.0"
+)
+
+# Download cross-platform deps (prefer binary, allow source for pure Python)
+for dep in "${DEPS[@]}"; do
+    pip download --quiet --dest "$WHEEL_DIR" \
+        --platform win_amd64 --python-version "3.11" \
+        --implementation cp --only-binary :all: \
+        "$dep" 2>/dev/null || \
+    pip download --quiet --dest "$WHEEL_DIR" \
+        --platform win_amd64 --python-version "3.11" \
+        --implementation cp \
+        "$dep" 2>/dev/null || \
+    pip download --quiet --dest "$WHEEL_DIR" "$dep" 2>/dev/null || \
+    echo "  WARNING: Could not download $dep (skipping)"
+done
+
+# Download Windows-only deps (best effort)
+for dep in "${WIN_DEPS[@]}"; do
+    pip download --quiet --dest "$WHEEL_DIR" \
+        --platform win_amd64 --python-version "3.11" \
+        --implementation cp --only-binary :all: \
+        "$dep" 2>/dev/null || \
+    pip download --quiet --dest "$WHEEL_DIR" \
+        --platform win_amd64 --python-version "3.11" \
+        --implementation cp \
+        "$dep" 2>/dev/null || \
+    echo "  WARNING: Could not download $dep (skipping, Windows-only)"
+done
+
+# Install all downloaded wheels into site-packages
+echo "  Installing $(ls "$WHEEL_DIR"/*.whl 2>/dev/null | wc -l) wheels into site-packages..."
+for whl in "$WHEEL_DIR"/*.whl; do
+    [ -f "$whl" ] && unzip -qo "$whl" -d "$SITE_PACKAGES" 2>/dev/null || true
+done
+
+# Also extract any .tar.gz source packages (pure Python only)
+for sdist in "$WHEEL_DIR"/*.tar.gz; do
+    [ -f "$sdist" ] || continue
+    TMPDIR=$(mktemp -d)
+    tar -xzf "$sdist" -C "$TMPDIR" 2>/dev/null || continue
+    # Find the package directory inside and copy it
+    PKG_DIR=$(find "$TMPDIR" -maxdepth 2 -name "*.py" -path "*/setup.py" -exec dirname {} \; | head -1)
+    if [ -n "$PKG_DIR" ] && [ -d "$PKG_DIR/src" ]; then
+        cp -r "$PKG_DIR/src/"* "$SITE_PACKAGES/" 2>/dev/null || true
+    elif [ -n "$PKG_DIR" ]; then
+        # Copy any Python package directories
+        find "$PKG_DIR" -maxdepth 1 -type d -name "[a-z]*" -exec cp -r {} "$SITE_PACKAGES/" \; 2>/dev/null || true
+    fi
+    rm -rf "$TMPDIR"
+done
+
+# ── Reduce package size ────────────────────────────────────────
+echo "  Cleaning up to reduce size..."
+
+# Remove caches, tests, docs, type stubs
+find "$SITE_PACKAGES" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+find "$SITE_PACKAGES" -type d -name tests -exec rm -rf {} + 2>/dev/null || true
+find "$SITE_PACKAGES" -type d -name test -exec rm -rf {} + 2>/dev/null || true
+find "$SITE_PACKAGES" -type d -name "*.dist-info" -exec rm -rf {} + 2>/dev/null || true
+find "$SITE_PACKAGES" -name "*.pyi" -delete 2>/dev/null || true
+
+# Remove pip and setuptools (not needed at runtime)
+rm -rf "$SITE_PACKAGES"/pip "$SITE_PACKAGES"/pip-* 2>/dev/null || true
+rm -rf "$SITE_PACKAGES"/setuptools "$SITE_PACKAGES"/setuptools-* "$SITE_PACKAGES"/pkg_resources 2>/dev/null || true
+rm -rf "$SITE_PACKAGES"/_distutils_hack 2>/dev/null || true
+
+# Remove pythonwin GUI IDE and help file (ships with pywin32 but not needed)
+rm -rf "$SITE_PACKAGES"/pythonwin 2>/dev/null || true
+rm -f "$SITE_PACKAGES"/PyWin32.chm 2>/dev/null || true
+
+# OpenCV: remove ffmpeg DLL (28MB, only for video file I/O, not camera),
+# Haar cascades (2.6MB), and misc dev files
+CV2_DIR="$SITE_PACKAGES/cv2"
+if [ -d "$CV2_DIR" ]; then
+    rm -f "$CV2_DIR"/opencv_videoio_ffmpeg*.dll 2>/dev/null || true
+    rm -rf "$CV2_DIR/data" "$CV2_DIR/gapi" "$CV2_DIR/misc" "$CV2_DIR/utils" 2>/dev/null || true
+    rm -rf "$CV2_DIR/typing_stubs" "$CV2_DIR/typing" 2>/dev/null || true
+fi
+
+# numpy: remove tests, f2py, typing stubs
+rm -rf "$SITE_PACKAGES/numpy/tests" "$SITE_PACKAGES/numpy/*/tests" 2>/dev/null || true
+rm -rf "$SITE_PACKAGES/numpy/f2py" 2>/dev/null || true
+rm -rf "$SITE_PACKAGES/numpy/typing" 2>/dev/null || true
+rm -rf "$SITE_PACKAGES/numpy/_pyinstaller" 2>/dev/null || true
+
+# Pillow: remove unused image plugins' test data
+rm -rf "$SITE_PACKAGES/PIL/tests" 2>/dev/null || true
+
+# winrt: remove type stubs
+find "$SITE_PACKAGES/winrt" -name "*.pyi" -delete 2>/dev/null || true
+
+# Remove wled_controller if it got installed
+rm -rf "$SITE_PACKAGES"/wled_controller* "$SITE_PACKAGES"/wled*.dist-info 2>/dev/null || true
+
+CLEANED_SIZE=$(du -sh "$SITE_PACKAGES" | cut -f1)
+echo "  Site-packages after cleanup: $CLEANED_SIZE"
+
+WHEEL_COUNT=$(ls "$WHEEL_DIR"/*.whl 2>/dev/null | wc -l)
+echo "  Installed $WHEEL_COUNT packages"
+
+# ── Build frontend ───────────────────────────────────────────
+
+echo "[7/9] Building frontend bundle..."
+(cd "$SERVER_DIR" && npm ci --loglevel error && npm run build) 2>&1 | {
+    grep -v 'RemoteException' || true
+}
+
+# ── Copy application files ───────────────────────────────────
+
+echo "[8/9] Copying application files..."
+mkdir -p "$APP_DIR"
+
+cp -r "$SERVER_DIR/src" "$APP_DIR/src"
+cp -r "$SERVER_DIR/config" "$APP_DIR/config"
+mkdir -p "$DIST_DIR/data" "$DIST_DIR/logs"
+
+# Clean up source maps and __pycache__
+find "$APP_DIR" -name "*.map" -delete 2>/dev/null || true
+find "$APP_DIR" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# Pre-compile Python bytecode for faster startup
+echo "  Pre-compiling Python bytecode..."
+python -m compileall -b -q "$APP_DIR/src" 2>/dev/null || true
+python -m compileall -b -q "$SITE_PACKAGES" 2>/dev/null || true
+
+# ── Create launcher ──────────────────────────────────────────
+
+echo "[8b/9] Creating launcher and packaging..."
+
+cat > "$DIST_DIR/LedGrab.bat" << LAUNCHER
+@echo off
+title LedGrab v${VERSION_CLEAN}
+cd /d "%~dp0"
+
+:: Set paths
+set PYTHONPATH=%~dp0app\src
+set WLED_CONFIG_PATH=%~dp0app\config\default_config.yaml
+
+:: Create data directory if missing
+if not exist "%~dp0data" mkdir "%~dp0data"
+if not exist "%~dp0logs" mkdir "%~dp0logs"
+
+:: Start the server — reads port from config, prints its own banner
+"%~dp0python\python.exe" -m wled_controller.main
+
+pause
+LAUNCHER
+
+# Convert launcher to Windows line endings
+sed -i 's/$/\r/' "$DIST_DIR/LedGrab.bat"
+
+# ── Create autostart scripts ─────────────────────────────────
+
+cat > "$DIST_DIR/install-autostart.bat" << 'AUTOSTART'
+@echo off
+:: Install LedGrab to start automatically on Windows login
+:: Creates a shortcut in the Startup folder
+
+set SHORTCUT_NAME=LedGrab
+set STARTUP_DIR=%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup
+set TARGET=%~dp0LedGrab.bat
+set SHORTCUT=%STARTUP_DIR%\%SHORTCUT_NAME%.lnk
+
+echo Installing LedGrab autostart...
+
+:: Use PowerShell to create a proper shortcut
+powershell -NoProfile -Command ^
+  "$ws = New-Object -ComObject WScript.Shell; ^
+   $sc = $ws.CreateShortcut('%SHORTCUT%'); ^
+   $sc.TargetPath = '%TARGET%'; ^
+   $sc.WorkingDirectory = '%~dp0'; ^
+   $sc.WindowStyle = 7; ^
+   $sc.Description = 'LedGrab ambient lighting server'; ^
+   $sc.Save()"
+
+if exist "%SHORTCUT%" (
+    echo.
+    echo  [OK] LedGrab will start automatically on login.
+    echo  Shortcut: %SHORTCUT%
+    echo.
+    echo  To remove: run uninstall-autostart.bat
+) else (
+    echo.
+    echo  [ERROR] Failed to create shortcut.
+)
+
+pause
+AUTOSTART
+sed -i 's/$/\r/' "$DIST_DIR/install-autostart.bat"
+
+cat > "$DIST_DIR/uninstall-autostart.bat" << 'UNAUTOSTART'
+@echo off
+:: Remove LedGrab from Windows startup
+
+set SHORTCUT=%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\LedGrab.lnk
+
+if exist "%SHORTCUT%" (
+    del "%SHORTCUT%"
+    echo.
+    echo  [OK] LedGrab autostart removed.
+) else (
+    echo.
+    echo  LedGrab autostart was not installed.
+)
+
+pause
+UNAUTOSTART
+sed -i 's/$/\r/' "$DIST_DIR/uninstall-autostart.bat"
+
+# ── Create ZIP ───────────────────────────────────────────────
+
+ZIP_PATH="$BUILD_DIR/$ZIP_NAME"
+rm -f "$ZIP_PATH"
+
+(cd "$BUILD_DIR" && zip -rq "$ZIP_NAME" "$DIST_NAME")
+
+ZIP_SIZE=$(du -h "$ZIP_PATH" | cut -f1)
+
+# ── Build NSIS installer (if makensis is available) ──────────
+
+SETUP_NAME="LedGrab-v${VERSION_CLEAN}-win-x64-setup.exe"
+SETUP_PATH="$BUILD_DIR/$SETUP_NAME"
+
+if command -v makensis &>/dev/null; then
+    echo "[9/9] Building NSIS installer..."
+    makensis -DVERSION="${VERSION_CLEAN}" "$SCRIPT_DIR/installer.nsi"
+    if [ -f "$SETUP_PATH" ]; then
+        SETUP_SIZE=$(du -h "$SETUP_PATH" | cut -f1)
+        echo "  Installer: $SETUP_PATH ($SETUP_SIZE)"
+    else
+        echo "  WARNING: makensis ran but installer not found at $SETUP_PATH"
+    fi
+else
+    echo "[9/9] Skipping installer (makensis not found — install nsis to enable)"
+fi
+
+echo ""
+echo "=== Build complete ==="
+echo "  ZIP: $ZIP_PATH ($ZIP_SIZE)"
+if [ -f "$SETUP_PATH" ]; then
+    echo "  Installer: $SETUP_PATH ($SETUP_SIZE)"
+fi
+echo ""
--- a/build-dist.ps1
+++ b/build-dist.ps1
@@ -106,6 +106,11 @@ $pthContent = $pthContent -replace '#\s*import site', 'import site'
 if ($pthContent -notmatch 'Lib\\site-packages') {
    $pthContent = $pthContent.TrimEnd() + "`nLib\site-packages`n"
 }
+# Embedded Python ._pth overrides PYTHONPATH, so add the app source path
+# directly for wled_controller to be importable
+if ($pthContent -notmatch '\.\.[/\\]app[/\\]src') {
+    $pthContent = $pthContent.TrimEnd() + "`n..\app\src`n"
+}
 Set-Content -Path $pthFile.FullName -Value $pthContent -NoNewline
 Write-Host "  Patched $($pthFile.Name)"

--- a/build-dist.sh
+++ b/build-dist.sh
@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+#
+# Build a portable Linux distribution of LedGrab.
+# Produces a self-contained tarball with virtualenv and launcher script.
+#
+# Usage:
+#   ./build-dist.sh [VERSION]
+#   ./build-dist.sh v0.1.0-alpha.1
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BUILD_DIR="$SCRIPT_DIR/build"
+DIST_NAME="LedGrab"
+DIST_DIR="$BUILD_DIR/$DIST_NAME"
+SERVER_DIR="$SCRIPT_DIR/server"
+VENV_DIR="$DIST_DIR/venv"
+APP_DIR="$DIST_DIR/app"
+
+# ── Version detection ────────────────────────────────────────
+
+VERSION="${1:-}"
+
+if [ -z "$VERSION" ]; then
+    VERSION=$(git describe --tags --exact-match 2>/dev/null || true)
+fi
+if [ -z "$VERSION" ]; then
+    VERSION="${GITEA_REF_NAME:-${GITHUB_REF_NAME:-}}"
+fi
+if [ -z "$VERSION" ]; then
+    VERSION=$(grep -oP '__version__\s*=\s*"\K[^"]+' "$SERVER_DIR/src/wled_controller/__init__.py" 2>/dev/null || echo "0.0.0")
+fi
+
+VERSION_CLEAN="${VERSION#v}"
+TAR_NAME="LedGrab-v${VERSION_CLEAN}-linux-x64.tar.gz"
+
+echo "=== Building LedGrab v${VERSION_CLEAN} (Linux) ==="
+echo "  Output: build/$TAR_NAME"
+echo ""
+
+# ── Clean ────────────────────────────────────────────────────
+
+if [ -d "$DIST_DIR" ]; then
+    echo "[1/7] Cleaning previous build..."
+    rm -rf "$DIST_DIR"
+fi
+mkdir -p "$DIST_DIR"
+
+# ── Create virtualenv ────────────────────────────────────────
+
+echo "[2/7] Creating virtualenv..."
+python3 -m venv "$VENV_DIR"
+source "$VENV_DIR/bin/activate"
+pip install --upgrade pip --quiet
+
+# ── Install dependencies ─────────────────────────────────────
+
+echo "[3/7] Installing dependencies..."
+pip install --quiet "${SERVER_DIR}[camera,notifications]" 2>&1 | {
+    grep -i 'error\|failed' || true
+}
+
+# Remove the installed wled_controller package (PYTHONPATH handles app code)
+SITE_PACKAGES="$VENV_DIR/lib/python*/site-packages"
+rm -rf $SITE_PACKAGES/wled_controller* $SITE_PACKAGES/wled*.dist-info 2>/dev/null || true
+
+# Clean up caches
+find "$VENV_DIR" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+find "$VENV_DIR" -type d -name tests -exec rm -rf {} + 2>/dev/null || true
+find "$VENV_DIR" -type d -name test -exec rm -rf {} + 2>/dev/null || true
+
+# ── Build frontend ───────────────────────────────────────────
+
+echo "[4/7] Building frontend bundle..."
+(cd "$SERVER_DIR" && npm ci --loglevel error && npm run build) 2>&1 | {
+    grep -v 'RemoteException' || true
+}
+
+# ── Copy application files ───────────────────────────────────
+
+echo "[5/7] Copying application files..."
+mkdir -p "$APP_DIR"
+
+cp -r "$SERVER_DIR/src" "$APP_DIR/src"
+cp -r "$SERVER_DIR/config" "$APP_DIR/config"
+mkdir -p "$DIST_DIR/data" "$DIST_DIR/logs"
+
+# Clean up source maps and __pycache__
+find "$APP_DIR" -name "*.map" -delete 2>/dev/null || true
+find "$APP_DIR" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# ── Create launcher ──────────────────────────────────────────
+
+echo "[6/7] Creating launcher..."
+cat > "$DIST_DIR/run.sh" << 'LAUNCHER'
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+export PYTHONPATH="$SCRIPT_DIR/app/src"
+export WLED_CONFIG_PATH="$SCRIPT_DIR/app/config/default_config.yaml"
+
+mkdir -p "$SCRIPT_DIR/data" "$SCRIPT_DIR/logs"
+
+source "$SCRIPT_DIR/venv/bin/activate"
+exec python -m wled_controller.main
+LAUNCHER
+
+sed -i "s/VERSION_PLACEHOLDER/${VERSION_CLEAN}/" "$DIST_DIR/run.sh"
+chmod +x "$DIST_DIR/run.sh"
+
+# ── Create autostart scripts ─────────────────────────────────
+
+cat > "$DIST_DIR/install-service.sh" << 'SERVICE_INSTALL'
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SERVICE_NAME="ledgrab"
+SERVICE_FILE="/etc/systemd/system/${SERVICE_NAME}.service"
+RUN_SCRIPT="$SCRIPT_DIR/run.sh"
+CURRENT_USER="$(whoami)"
+
+if [ "$EUID" -ne 0 ] && [ "$CURRENT_USER" != "root" ]; then
+    echo "This script requires root privileges. Re-running with sudo..."
+    exec sudo "$0" "$@"
+fi
+
+# Resolve the actual user (not root) when run via sudo
+ACTUAL_USER="${SUDO_USER:-$CURRENT_USER}"
+ACTUAL_HOME=$(eval echo "~$ACTUAL_USER")
+
+echo "Installing LedGrab systemd service..."
+
+cat > "$SERVICE_FILE" << EOF
+[Unit]
+Description=LedGrab ambient lighting server
+After=network.target
+
+[Service]
+Type=simple
+User=$ACTUAL_USER
+WorkingDirectory=$SCRIPT_DIR
+ExecStart=$RUN_SCRIPT
+Restart=on-failure
+RestartSec=5
+Environment=HOME=$ACTUAL_HOME
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable "$SERVICE_NAME"
+systemctl start "$SERVICE_NAME"
+
+echo ""
+echo "  [OK] LedGrab service installed and started."
+echo ""
+echo "  Commands:"
+echo "    sudo systemctl status $SERVICE_NAME    # Check status"
+echo "    sudo systemctl stop $SERVICE_NAME      # Stop"
+echo "    sudo systemctl restart $SERVICE_NAME   # Restart"
+echo "    sudo journalctl -u $SERVICE_NAME -f    # View logs"
+echo ""
+echo "  To remove: run ./uninstall-service.sh"
+SERVICE_INSTALL
+chmod +x "$DIST_DIR/install-service.sh"
+
+cat > "$DIST_DIR/uninstall-service.sh" << 'SERVICE_UNINSTALL'
+#!/usr/bin/env bash
+set -euo pipefail
+
+SERVICE_NAME="ledgrab"
+SERVICE_FILE="/etc/systemd/system/${SERVICE_NAME}.service"
+
+if [ "$EUID" -ne 0 ] && [ "$(whoami)" != "root" ]; then
+    echo "This script requires root privileges. Re-running with sudo..."
+    exec sudo "$0" "$@"
+fi
+
+if [ ! -f "$SERVICE_FILE" ]; then
+    echo "LedGrab service is not installed."
+    exit 0
+fi
+
+echo "Removing LedGrab systemd service..."
+
+systemctl stop "$SERVICE_NAME" 2>/dev/null || true
+systemctl disable "$SERVICE_NAME" 2>/dev/null || true
+rm -f "$SERVICE_FILE"
+systemctl daemon-reload
+
+echo ""
+echo "  [OK] LedGrab service removed."
+SERVICE_UNINSTALL
+chmod +x "$DIST_DIR/uninstall-service.sh"
+
+# ── Create tarball ───────────────────────────────────────────
+
+echo "[7/7] Creating $TAR_NAME..."
+deactivate 2>/dev/null || true
+
+TAR_PATH="$BUILD_DIR/$TAR_NAME"
+(cd "$BUILD_DIR" && tar -czf "$TAR_NAME" "$DIST_NAME")
+
+TAR_SIZE=$(du -h "$TAR_PATH" | cut -f1)
+echo ""
+echo "=== Build complete ==="
+echo "  Archive: $TAR_PATH"
+echo "  Size: $TAR_SIZE"
+echo ""
--- a/installer.nsi
+++ b/installer.nsi
@@ -0,0 +1,146 @@
+; LedGrab NSIS Installer Script
+; Cross-compilable on Linux: apt install nsis && makensis installer.nsi
+;
+; Expects the portable build to already exist at build/LedGrab/
+; (run build-dist-windows.sh first)
+
+!include "MUI2.nsh"
+!include "FileFunc.nsh"
+
+; ── Metadata ────────────────────────────────────────────────
+
+!define APPNAME "LedGrab"
+!define DESCRIPTION "Ambient lighting system — captures screen content and drives LED strips in real time"
+!define VERSIONMAJOR 0
+!define VERSIONMINOR 1
+!define VERSIONBUILD 0
+
+; Set from command line: makensis -DVERSION=0.1.0 installer.nsi
+!ifndef VERSION
+  !define VERSION "${VERSIONMAJOR}.${VERSIONMINOR}.${VERSIONBUILD}"
+!endif
+
+Name "${APPNAME} v${VERSION}"
+OutFile "build\${APPNAME}-v${VERSION}-win-x64-setup.exe"
+InstallDir "$LOCALAPPDATA\${APPNAME}"
+InstallDirRegKey HKCU "Software\${APPNAME}" "InstallDir"
+RequestExecutionLevel user
+SetCompressor /SOLID lzma
+
+; ── Modern UI Configuration ─────────────────────────────────
+
+!define MUI_ABORTWARNING
+
+; ── Pages ───────────────────────────────────────────────────
+
+!insertmacro MUI_PAGE_WELCOME
+!insertmacro MUI_PAGE_DIRECTORY
+!insertmacro MUI_PAGE_COMPONENTS
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_PAGE_FINISH
+
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+
+!insertmacro MUI_LANGUAGE "English"
+
+; ── Installer Sections ──────────────────────────────────────
+
+Section "!${APPNAME} (required)" SecCore
+  SectionIn RO
+
+  SetOutPath "$INSTDIR"
+
+  ; Copy the entire portable build
+  File /r "build\LedGrab\python"
+  File /r "build\LedGrab\app"
+  File "build\LedGrab\LedGrab.bat"
+
+  ; Create data and logs directories
+  CreateDirectory "$INSTDIR\data"
+  CreateDirectory "$INSTDIR\logs"
+
+  ; Create uninstaller
+  WriteUninstaller "$INSTDIR\uninstall.exe"
+
+  ; Start Menu shortcuts
+  CreateDirectory "$SMPROGRAMS\${APPNAME}"
+  CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
+    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+  CreateShortcut "$SMPROGRAMS\${APPNAME}\Uninstall.lnk" "$INSTDIR\uninstall.exe"
+
+  ; Registry: install location + Add/Remove Programs entry
+  WriteRegStr HKCU "Software\${APPNAME}" "InstallDir" "$INSTDIR"
+  WriteRegStr HKCU "Software\${APPNAME}" "Version" "${VERSION}"
+
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "DisplayName" "${APPNAME}"
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "DisplayVersion" "${VERSION}"
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "UninstallString" '"$INSTDIR\uninstall.exe"'
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "InstallLocation" "$INSTDIR"
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "Publisher" "Alexei Dolgolyov"
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "URLInfoAbout" "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"
+  WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "NoModify" 1
+  WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "NoRepair" 1
+
+  ; Calculate installed size for Add/Remove Programs
+  ${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2
+  IntFmt $0 "0x%08X" $0
+  WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "EstimatedSize" "$0"
+SectionEnd
+
+Section "Desktop shortcut" SecDesktop
+  CreateShortcut "$DESKTOP\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
+    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+SectionEnd
+
+Section "Start with Windows" SecAutostart
+  CreateShortcut "$SMSTARTUP\${APPNAME}.lnk" "$INSTDIR\LedGrab.bat" \
+    "" "" "" SW_SHOWMINIMIZED "" "${DESCRIPTION}"
+SectionEnd
+
+; ── Section Descriptions ────────────────────────────────────
+
+!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
+  !insertmacro MUI_DESCRIPTION_TEXT ${SecCore} \
+    "Install ${APPNAME} server and all required files."
+  !insertmacro MUI_DESCRIPTION_TEXT ${SecDesktop} \
+    "Create a shortcut on your desktop."
+  !insertmacro MUI_DESCRIPTION_TEXT ${SecAutostart} \
+    "Start ${APPNAME} automatically when you log in."
+!insertmacro MUI_FUNCTION_DESCRIPTION_END
+
+; ── Uninstaller ─────────────────────────────────────────────
+
+Section "Uninstall"
+  ; Remove shortcuts
+  Delete "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk"
+  Delete "$SMPROGRAMS\${APPNAME}\Uninstall.lnk"
+  RMDir "$SMPROGRAMS\${APPNAME}"
+  Delete "$DESKTOP\${APPNAME}.lnk"
+  Delete "$SMSTARTUP\${APPNAME}.lnk"
+
+  ; Remove application files (but NOT data/ — preserve user config)
+  RMDir /r "$INSTDIR\python"
+  RMDir /r "$INSTDIR\app"
+  Delete "$INSTDIR\LedGrab.bat"
+  Delete "$INSTDIR\uninstall.exe"
+
+  ; Remove logs (but keep data/)
+  RMDir /r "$INSTDIR\logs"
+
+  ; Try to remove install dir (only succeeds if empty — data/ may remain)
+  RMDir "$INSTDIR"
+
+  ; Remove registry keys
+  DeleteRegKey HKCU "Software\${APPNAME}"
+  DeleteRegKey HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}"
+SectionEnd
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -37,7 +37,6 @@ dependencies = [
    "python-dateutil>=2.9.0",
    "python-multipart>=0.0.12",
    "jinja2>=3.1.0",
-    "wmi>=1.5.1; sys_platform == 'win32'",
    "zeroconf>=0.131.0",
    "pyserial>=3.5",
    "psutil>=5.9.0",
@@ -61,9 +60,13 @@ dev = [
 camera = [
    "opencv-python-headless>=4.8.0",
 ]
-# OS notification capture
+# OS notification capture (winrt packages are ~2.5MB total vs winsdk's ~35MB)
 notifications = [
-    "winsdk>=1.0.0b10; sys_platform == 'win32'",
+    "winrt-Windows.UI.Notifications>=3.0.0; sys_platform == 'win32'",
+    "winrt-Windows.UI.Notifications.Management>=3.0.0; sys_platform == 'win32'",
+    "winrt-Windows.Foundation>=3.0.0; sys_platform == 'win32'",
+    "winrt-Windows.Foundation.Collections>=3.0.0; sys_platform == 'win32'",
+    "winrt-Windows.ApplicationModel>=3.0.0; sys_platform == 'win32'",
    "dbus-next>=0.2.3; sys_platform == 'linux'",
 ]
 # High-performance screen capture engines (Windows only)
--- a/server/src/wled_controller/api/routes/_preview_helpers.py
+++ b/server/src/wled_controller/api/routes/_preview_helpers.py
@@ -43,15 +43,14 @@ def _encode_jpeg(pil_image: Image.Image, quality: int = 85) -> str:

 def encode_preview_frame(image: np.ndarray, max_width: int = None, quality: int = 80) -> bytes:
    """Encode a numpy RGB image to JPEG bytes, optionally downscaling."""
-    import cv2
+    pil_img = Image.fromarray(image)
    if max_width and image.shape[1] > max_width:
        scale = max_width / image.shape[1]
        new_h = int(image.shape[0] * scale)
-        image = cv2.resize(image, (max_width, new_h), interpolation=cv2.INTER_AREA)
-    # RGB -> BGR for OpenCV JPEG encoding
-    bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
-    _, buf = cv2.imencode('.jpg', bgr, [cv2.IMWRITE_JPEG_QUALITY, quality])
-    return buf.tobytes()
+        pil_img = pil_img.resize((max_width, new_h), Image.LANCZOS)
+    buf = io.BytesIO()
+    pil_img.save(buf, format="JPEG", quality=quality)
+    return buf.getvalue()


 def _make_thumbnail(pil_image: Image.Image, max_width: int) -> Image.Image:
--- a/server/src/wled_controller/core/automations/platform_detector.py
+++ b/server/src/wled_controller/core/automations/platform_detector.py
@@ -1,6 +1,6 @@
 """Platform-specific process and window detection.

-Windows: uses wmi for process listing, ctypes for foreground window detection.
+Windows: uses ctypes for process listing and foreground window detection.
 Non-Windows: graceful degradation (returns empty results).
 """

@@ -37,7 +37,7 @@ class PlatformDetector:
            user32 = ctypes.windll.user32

            WNDPROC = ctypes.WINFUNCTYPE(
-                ctypes.c_long,
+                ctypes.c_ssize_t,  # LRESULT (64-bit on x64)
                ctypes.wintypes.HWND,
                ctypes.c_uint,
                ctypes.wintypes.WPARAM,
@@ -60,6 +60,12 @@ class PlatformDetector:
                0x8F, 0x24, 0xC2, 0x8D, 0x93, 0x6F, 0xDA, 0x47,
            )

+            user32.DefWindowProcW.argtypes = [
+                ctypes.wintypes.HWND, ctypes.c_uint,
+                ctypes.wintypes.WPARAM, ctypes.wintypes.LPARAM,
+            ]
+            user32.DefWindowProcW.restype = ctypes.c_ssize_t
+
            def wnd_proc(hwnd, msg, wparam, lparam):
                if msg == WM_POWERBROADCAST and wparam == PBT_POWERSETTINGCHANGE:
                    try:
--- a/server/src/wled_controller/core/capture/screen_overlay.py
+++ b/server/src/wled_controller/core/capture/screen_overlay.py
@@ -278,7 +278,12 @@ class OverlayManager:

    def _start_tk_thread(self) -> None:
        def _run():
-            import tkinter as tk  # lazy import — tkinter unavailable in headless CI
+            try:
+                import tkinter as tk  # lazy import — tkinter unavailable in embedded Python / headless CI
+            except ImportError:
+                logger.warning("tkinter not available — screen overlay disabled")
+                self._tk_ready.set()
+                return

            try:
                self._tk_root = tk.Tk()
--- a/server/src/wled_controller/core/capture_engines/camera_engine.py
+++ b/server/src/wled_controller/core/capture_engines/camera_engine.py
@@ -56,21 +56,115 @@ def _cv2_backend_id(backend_name: str) -> Optional[int]:
 def _get_camera_friendly_names() -> Dict[int, str]:
    """Get friendly names for cameras from OS.

-    On Windows, queries WMI for PnP camera devices.
-    Returns a dict mapping sequential index → friendly name.
+    On Windows, enumerates camera devices via the SetupAPI (pure ctypes,
+    no third-party dependencies).  Uses the camera device class GUID
+    ``{ca3e7ab9-b4c3-4ae6-8251-579ef933890f}``.
+
+    Returns a dict mapping sequential index to friendly name.
    """
    if platform.system() != "Windows":
        return {}

    try:
-        import wmi
-        c = wmi.WMI()
-        cameras = c.query(
-            "SELECT Name FROM Win32_PnPEntity WHERE PNPClass = 'Camera'"
+        import ctypes
+        from ctypes import wintypes
+
+        # ── SetupAPI types ────────────────────────────────────────
+        class GUID(ctypes.Structure):
+            _fields_ = [
+                ("Data1", wintypes.DWORD),
+                ("Data2", wintypes.WORD),
+                ("Data3", wintypes.WORD),
+                ("Data4", ctypes.c_ubyte * 8),
+            ]
+
+        class SP_DEVINFO_DATA(ctypes.Structure):
+            _fields_ = [
+                ("cbSize", wintypes.DWORD),
+                ("ClassGuid", GUID),
+                ("DevInst", wintypes.DWORD),
+                ("Reserved", ctypes.POINTER(ctypes.c_ulong)),
+            ]
+
+        setupapi = ctypes.windll.setupapi
+
+        # Camera device class GUID: {ca3e7ab9-b4c3-4ae6-8251-579ef933890f}
+        GUID_DEVCLASS_CAMERA = GUID(
+            0xCA3E7AB9, 0xB4C3, 0x4AE6,
+            (ctypes.c_ubyte * 8)(0x82, 0x51, 0x57, 0x9E, 0xF9, 0x33, 0x89, 0x0F),
        )
-        return {i: cam.Name for i, cam in enumerate(cameras)}
+
+        DIGCF_PRESENT = 0x00000002
+        SPDRP_FRIENDLYNAME = 0x0000000C
+        SPDRP_DEVICEDESC = 0x00000000
+        INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+
+        # SetupDiGetClassDevsW → HDEVINFO
+        setupapi.SetupDiGetClassDevsW.restype = ctypes.c_void_p
+        setupapi.SetupDiGetClassDevsW.argtypes = [
+            ctypes.POINTER(GUID), ctypes.c_wchar_p,
+            ctypes.c_void_p, wintypes.DWORD,
+        ]
+
+        # SetupDiEnumDeviceInfo → BOOL
+        setupapi.SetupDiEnumDeviceInfo.restype = wintypes.BOOL
+        setupapi.SetupDiEnumDeviceInfo.argtypes = [
+            ctypes.c_void_p, wintypes.DWORD, ctypes.POINTER(SP_DEVINFO_DATA),
+        ]
+
+        # SetupDiGetDeviceRegistryPropertyW → BOOL
+        setupapi.SetupDiGetDeviceRegistryPropertyW.restype = wintypes.BOOL
+        setupapi.SetupDiGetDeviceRegistryPropertyW.argtypes = [
+            ctypes.c_void_p, ctypes.POINTER(SP_DEVINFO_DATA),
+            wintypes.DWORD, ctypes.POINTER(wintypes.DWORD),
+            ctypes.c_void_p, wintypes.DWORD, ctypes.POINTER(wintypes.DWORD),
+        ]
+
+        # SetupDiDestroyDeviceInfoList → BOOL
+        setupapi.SetupDiDestroyDeviceInfoList.restype = wintypes.BOOL
+        setupapi.SetupDiDestroyDeviceInfoList.argtypes = [ctypes.c_void_p]
+
+        # ── Enumerate cameras ─────────────────────────────────────
+        hdevinfo = setupapi.SetupDiGetClassDevsW(
+            ctypes.byref(GUID_DEVCLASS_CAMERA), None, None, DIGCF_PRESENT,
+        )
+        if hdevinfo == INVALID_HANDLE_VALUE:
+            return {}
+
+        cameras: Dict[int, str] = {}
+        idx = 0
+
+        try:
+            while True:
+                devinfo = SP_DEVINFO_DATA()
+                devinfo.cbSize = ctypes.sizeof(SP_DEVINFO_DATA)
+
+                if not setupapi.SetupDiEnumDeviceInfo(hdevinfo, idx, ctypes.byref(devinfo)):
+                    break  # ERROR_NO_MORE_ITEMS
+
+                # Try SPDRP_FRIENDLYNAME first, fall back to SPDRP_DEVICEDESC
+                name = None
+                buf = ctypes.create_unicode_buffer(256)
+                buf_size = wintypes.DWORD(ctypes.sizeof(buf))
+
+                for prop in (SPDRP_FRIENDLYNAME, SPDRP_DEVICEDESC):
+                    if setupapi.SetupDiGetDeviceRegistryPropertyW(
+                        hdevinfo, ctypes.byref(devinfo), prop,
+                        None, buf, buf_size, None,
+                    ):
+                        name = buf.value.strip()
+                        if name:
+                            break
+
+                cameras[idx] = name if name else f"Camera {idx}"
+                idx += 1
+        finally:
+            setupapi.SetupDiDestroyDeviceInfoList(hdevinfo)
+
+        return cameras
+
    except Exception as e:
-        logger.debug(f"WMI camera enumeration failed: {e}")
+        logger.debug(f"SetupAPI camera enumeration failed: {e}")
        return {}


--- a/server/src/wled_controller/core/filters/color_correction.py
+++ b/server/src/wled_controller/core/filters/color_correction.py
@@ -3,7 +3,6 @@
 import math
 from typing import Any, Dict, List, Optional

-import cv2
 import numpy as np

 from wled_controller.core.filters.base import FilterOptionDef, PostprocessingFilter
@@ -69,12 +68,12 @@ class ColorCorrectionFilter(PostprocessingFilter):
        g_mult = (tg / _REF_G) * gg
        b_mult = (tb / _REF_B) * bg

-        # Build merged (256, 1, 3) LUT for single-pass cv2.LUT
+        # Build merged (256, 3) LUT for single-pass numpy fancy-index lookup
        src = np.arange(256, dtype=np.float32)
        lut_r = np.clip(src * r_mult, 0, 255).astype(np.uint8)
        lut_g = np.clip(src * g_mult, 0, 255).astype(np.uint8)
        lut_b = np.clip(src * b_mult, 0, 255).astype(np.uint8)
-        self._lut = np.stack([lut_r, lut_g, lut_b], axis=-1).reshape(256, 1, 3)
+        self._lut = np.stack([lut_r, lut_g, lut_b], axis=-1)  # (256, 3)

        self._is_neutral = (temp == 6500 and rg == 1.0 and gg == 1.0 and bg == 1.0)

@@ -122,5 +121,5 @@ class ColorCorrectionFilter(PostprocessingFilter):
    def process_image(self, image: np.ndarray, image_pool: ImagePool) -> Optional[np.ndarray]:
        if self._is_neutral:
            return None
-        cv2.LUT(image, self._lut, dst=image)
+        image[:] = self._lut[image]
        return None
--- a/server/src/wled_controller/core/filters/downscaler.py
+++ b/server/src/wled_controller/core/filters/downscaler.py
@@ -2,8 +2,8 @@

 from typing import List, Optional

-import cv2
 import numpy as np
+from PIL import Image

 from wled_controller.core.filters.base import FilterOptionDef, PostprocessingFilter
 from wled_controller.core.filters.image_pool import ImagePool
@@ -44,7 +44,8 @@ class DownscalerFilter(PostprocessingFilter):
        if new_h == h and new_w == w:
            return None

-        downscaled = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+        pil_img = Image.fromarray(image)
+        downscaled = np.array(pil_img.resize((new_w, new_h), Image.LANCZOS))

        result = image_pool.acquire(new_h, new_w, image.shape[2] if image.ndim == 3 else 3)
        np.copyto(result, downscaled)
--- a/server/src/wled_controller/core/filters/pixelate.py
+++ b/server/src/wled_controller/core/filters/pixelate.py
@@ -2,8 +2,8 @@

 from typing import List, Optional

-import cv2
 import numpy as np
+from PIL import Image

 from wled_controller.core.filters.base import FilterOptionDef, PostprocessingFilter
 from wled_controller.core.filters.image_pool import ImagePool
@@ -42,8 +42,9 @@ class PixelateFilter(PostprocessingFilter):
        # vectorized C++ instead of per-block Python loop
        small_w = max(1, w // block_size)
        small_h = max(1, h // block_size)
-        small = cv2.resize(image, (small_w, small_h), interpolation=cv2.INTER_AREA)
-        pixelated = cv2.resize(small, (w, h), interpolation=cv2.INTER_NEAREST)
+        pil_img = Image.fromarray(image)
+        small = pil_img.resize((small_w, small_h), Image.LANCZOS)
+        pixelated = np.array(small.resize((w, h), Image.NEAREST))
        np.copyto(image, pixelated)

        return None
--- a/server/src/wled_controller/core/processing/kc_target_processor.py
+++ b/server/src/wled_controller/core/processing/kc_target_processor.py
@@ -9,8 +9,8 @@ import time
 from datetime import datetime, timezone
 from typing import Dict, List, Optional, Tuple

-import cv2
 import numpy as np
+from PIL import Image

 from wled_controller.core.processing.live_stream import LiveStream
 from wled_controller.core.capture.screen_capture import (
@@ -46,7 +46,8 @@ def _process_kc_frame(capture, rect_names, rect_bounds, calc_fn, prev_colors_arr
    t0 = time.perf_counter()

    # Downsample to working resolution — 144x fewer pixels at 1080p
-    small = cv2.resize(capture.image, KC_WORK_SIZE, interpolation=cv2.INTER_AREA)
+    pil_img = Image.fromarray(capture.image)
+    small = np.array(pil_img.resize(KC_WORK_SIZE, Image.LANCZOS))

    # Extract colors for each rectangle from the small image
    n = len(rect_names)
--- a/server/src/wled_controller/core/processing/os_notification_listener.py
+++ b/server/src/wled_controller/core/processing/os_notification_listener.py
@@ -5,7 +5,8 @@ instances when new notifications appear.  Sources with os_listener=True are
 monitored.

 Supported platforms:
- **Windows**: polls toast notifications via winsdk UserNotificationListener
+- **Windows**: polls toast notifications via winrt UserNotificationListener
+  (falls back to winsdk if winrt packages are not installed)
 - **Linux**: monitors org.freedesktop.Notifications via D-Bus (dbus-next)
 """

@@ -33,8 +34,34 @@ def get_os_notification_listener() -> Optional["OsNotificationListener"]:

 # ── Platform backends ──────────────────────────────────────────────────

+def _import_winrt_notifications():
+    """Try to import WinRT notification APIs: winrt first, then winsdk fallback.
+
+    Returns (UserNotificationListener, UserNotificationListenerAccessStatus,
+    NotificationKinds, backend_name) or raises ImportError.
+    """
+    # Preferred: lightweight winrt packages (~1MB total)
+    try:
+        from winrt.windows.ui.notifications.management import (
+            UserNotificationListener,
+            UserNotificationListenerAccessStatus,
+        )
+        from winrt.windows.ui.notifications import NotificationKinds
+        return UserNotificationListener, UserNotificationListenerAccessStatus, NotificationKinds, "winrt"
+    except ImportError:
+        pass
+
+    # Fallback: winsdk (~35MB, may already be installed)
+    from winsdk.windows.ui.notifications.management import (
+        UserNotificationListener,
+        UserNotificationListenerAccessStatus,
+    )
+    from winsdk.windows.ui.notifications import NotificationKinds
+    return UserNotificationListener, UserNotificationListenerAccessStatus, NotificationKinds, "winsdk"
+
+
 class _WindowsBackend:
-    """Polls Windows toast notifications via winsdk."""
+    """Polls Windows toast notifications via winrt (preferred) or winsdk."""

    def __init__(self, on_notification):
        self._on_notification = on_notification
@@ -48,21 +75,22 @@ class _WindowsBackend:
        if platform.system() != "Windows":
            return False
        try:
-            from winsdk.windows.ui.notifications.management import (
-                UserNotificationListener,
-                UserNotificationListenerAccessStatus,
-            )
-            listener = UserNotificationListener.current
+            UNL, AccessStatus, _NK, backend = _import_winrt_notifications()
+            listener = UNL.current
            status = listener.get_access_status()
-            if status != UserNotificationListenerAccessStatus.ALLOWED:
+            if status != AccessStatus.ALLOWED:
                logger.warning(
                    f"OS notification listener: access denied (status={status}). "
                    "Enable notification access in Windows Settings > Privacy > Notifications."
                )
                return False
+            logger.info(f"OS notification listener: using {backend} backend")
            return True
        except ImportError:
-            logger.info("OS notification listener: winsdk not installed, skipping")
+            logger.info(
+                "OS notification listener: neither winrt nor winsdk installed, skipping. "
+                "Install with: pip install winrt-Windows.UI.Notifications winrt-Windows.UI.Notifications.Management"
+            )
            return False
        except Exception as e:
            logger.warning(f"OS notification listener: Windows init error: {e}")
@@ -84,10 +112,8 @@ class _WindowsBackend:
            self._thread = None

    def _poll_loop(self) -> None:
-        from winsdk.windows.ui.notifications.management import UserNotificationListener
-        from winsdk.windows.ui.notifications import NotificationKinds
-
-        listener = UserNotificationListener.current
+        UNL, _AccessStatus, NotificationKinds, _backend = _import_winrt_notifications()
+        listener = UNL.current
        loop = asyncio.new_event_loop()

        async def _get_notifications():
--- a/server/src/wled_controller/main.py
+++ b/server/src/wled_controller/main.py
@@ -98,6 +98,10 @@ async def lifespan(app: FastAPI):
    logger.info(f"Starting LED Grab v{__version__}")
    logger.info(f"Python version: {sys.version}")
    logger.info(f"Server listening on {config.server.host}:{config.server.port}")
+    print(f"\n  =============================================")
+    print(f"   LED Grab v{__version__}")
+    print(f"   Open http://localhost:{config.server.port} in your browser")
+    print(f"  =============================================\n")

    # Validate authentication configuration
    if not config.auth.api_keys:
--- a/server/src/wled_controller/static/js/features/streams-capture-templates.ts
+++ b/server/src/wled_controller/static/js/features/streams-capture-templates.ts
@@ -15,7 +15,7 @@ import {
 import { API_BASE, getHeaders, fetchWithAuth, escapeHtml } from '../core/api.ts';
 import { t } from '../core/i18n.ts';
 import { Modal } from '../core/modal.ts';
-import { showToast, showConfirm, showOverlaySpinner, hideOverlaySpinner, updateOverlayPreview, setupBackdropClose } from '../core/ui.ts';
+import { showToast, showConfirm, openLightbox, showOverlaySpinner, hideOverlaySpinner, updateOverlayPreview, setupBackdropClose } from '../core/ui.ts';
 import { openDisplayPicker, formatDisplayLabel } from './displays.ts';
 import {
    getEngineIcon,
@@ -500,7 +500,7 @@ export function _runTestViaWS(wsPath: string, queryParams: any = {}, firstMessag
            } else if (msg.type === 'result') {
                gotResult = true;
                hideOverlaySpinner();
-                (window as any).openLightbox(msg.full_image, buildTestStatsHtml(msg));
+                openLightbox(msg.full_image, buildTestStatsHtml(msg));
                ws.close();
            } else if (msg.type === 'error') {
                hideOverlaySpinner();
--- a/server/src/wled_controller/utils/monitor_names.py
+++ b/server/src/wled_controller/utils/monitor_names.py
@@ -1,5 +1,6 @@
 """Utility functions for retrieving friendly monitor/display names."""

+import ctypes
 import sys
 from typing import Dict

@@ -11,7 +12,8 @@ logger = get_logger(__name__)
 def get_monitor_names() -> Dict[int, str]:
    """Get friendly names for connected monitors.

-    On Windows, attempts to retrieve monitor names from WMI.
+    On Windows, enumerates display adapters and their monitors via
+    ``EnumDisplayDevicesW`` (pure ctypes, no third-party dependencies).
    On other platforms, returns empty dict (will fall back to generic names).

    Returns:
@@ -22,47 +24,68 @@ def get_monitor_names() -> Dict[int, str]:
        return {}

    try:
-        import wmi
+        from ctypes import wintypes

-        w = wmi.WMI(namespace="wmi")
-        monitors = w.WmiMonitorID()
+        class DISPLAY_DEVICEW(ctypes.Structure):
+            _fields_ = [
+                ("cb", wintypes.DWORD),
+                ("DeviceName", ctypes.c_wchar * 32),
+                ("DeviceString", ctypes.c_wchar * 128),
+                ("StateFlags", wintypes.DWORD),
+                ("DeviceID", ctypes.c_wchar * 128),
+                ("DeviceKey", ctypes.c_wchar * 128),
+            ]

-        monitor_names = {}
+        user32 = ctypes.windll.user32

-        for idx, monitor in enumerate(monitors):
-            try:
-                # Extract manufacturer name
-                manufacturer = ""
-                if monitor.ManufacturerName:
-                    manufacturer = "".join(chr(c) for c in monitor.ManufacturerName if c != 0)
+        DISPLAY_DEVICE_ACTIVE = 0x00000001
+        DISPLAY_DEVICE_ATTACHED_TO_DESKTOP = 0x00000002

-                # Extract user-friendly name
-                user_name = ""
-                if monitor.UserFriendlyName:
-                    user_name = "".join(chr(c) for c in monitor.UserFriendlyName if c != 0)
+        monitor_names: Dict[int, str] = {}
+        monitor_idx = 0

-                # Build friendly name
-                if user_name:
-                    friendly_name = user_name.strip()
-                elif manufacturer:
-                    friendly_name = f"{manufacturer.strip()} Monitor"
-                else:
-                    friendly_name = f"Display {idx}"
+        # Enumerate display adapters (GPUs / virtual outputs)
+        adapter_idx = 0
+        while adapter_idx < 16:  # safety limit
+            adapter = DISPLAY_DEVICEW()
+            adapter.cb = ctypes.sizeof(DISPLAY_DEVICEW)

-                monitor_names[idx] = friendly_name
-                logger.debug(f"Monitor {idx}: {friendly_name}")
+            if not user32.EnumDisplayDevicesW(None, adapter_idx, ctypes.byref(adapter), 0):
+                break
+            adapter_idx += 1

-            except Exception as e:
-                logger.debug(f"Failed to parse monitor {idx} name: {e}")
-                monitor_names[idx] = f"Display {idx}"
+            # Skip adapters not attached to the desktop
+            if not (adapter.StateFlags & DISPLAY_DEVICE_ATTACHED_TO_DESKTOP):
+                continue
+
+            # Enumerate monitors attached to this adapter
+            child_idx = 0
+            while child_idx < 16:  # safety limit
+                monitor = DISPLAY_DEVICEW()
+                monitor.cb = ctypes.sizeof(DISPLAY_DEVICEW)
+
+                if not user32.EnumDisplayDevicesW(
+                    adapter.DeviceName, child_idx, ctypes.byref(monitor), 0
+                ):
+                    break
+                child_idx += 1
+
+                if not (monitor.StateFlags & DISPLAY_DEVICE_ACTIVE):
+                    continue
+
+                # DeviceString contains the friendly name (e.g. "DELL U2718Q")
+                friendly_name = monitor.DeviceString.strip()
+                if not friendly_name:
+                    friendly_name = f"Display {monitor_idx}"
+
+                monitor_names[monitor_idx] = friendly_name
+                logger.debug(f"Monitor {monitor_idx}: {friendly_name}")
+                monitor_idx += 1

        return monitor_names

-    except ImportError:
-        logger.debug("WMI library not available - install with: pip install wmi")
-        return {}
    except Exception as e:
-        logger.debug(f"Failed to retrieve monitor names via WMI: {e}")
+        logger.debug(f"Failed to retrieve monitor names via EnumDisplayDevices: {e}")
        return {}
Author	SHA1	Message	Date
alexei.dolgolyov	8bed09a401	perf: pre-compile Python bytecode in portable build Some checks failed Build Release / create-release (push) Successful in 1s Details Lint & Test / test (push) Failing after 24s Details Build Release / build-linux (push) Successful in 1m11s Details Build Release / build-docker (push) Successful in 8s Details Build Release / build-windows (push) Successful in 2m51s Details Add compileall step to build-dist-windows.sh that generates .pyc files for both app source and site-packages. Saves ~100-200ms on startup by skipping parse/compile on first import.	2026-03-22 13:38:15 +03:00
alexei.dolgolyov	6a6c8b2c52	perf: reduce portable build size ~40MB — replace winsdk/wmi, migrate cv2 to Pillow Some checks failed Lint & Test / test (push) Failing after 19s Details - Replace winsdk (~35MB) with winrt packages (~2.5MB) for OS notification listener. API is identical, 93% size reduction. - Replace wmi (~3-5MB) with ctypes for monitor names (EnumDisplayDevicesW) and camera names (SetupAPI). Zero external dependency. - Migrate cv2.resize/imencode/LUT to Pillow/numpy in 5 files (filters, preview helpers, kc_target_processor). OpenCV only needed for camera and video stream now. - Fix DefWindowProcW ctypes overflow on 64-bit Python (pre-existing bug in platform_detector display power listener). - Fix openLightbox import in streams-capture-templates.ts (was using broken window cast instead of direct import). - Add mandatory data migration policy to CLAUDE.md after silent data loss incident from storage file rename without migration.	2026-03-22 13:35:01 +03:00
alexei.dolgolyov	4aa209f7d1	perf: strip OpenCV ffmpeg DLL and PyWin32 help from portable build Some checks failed Lint & Test / test (push) Failing after 14s Details - Remove opencv_videoio_ffmpeg (28MB) — only needed for video file I/O, camera capture uses cv2.VideoCapture which links directly to DirectShow - Remove PyWin32.chm help file (2.6MB) - Keep cv2.pyd intact (needed for resize, cvtColor, camera) Future: migrate non-camera cv2 usage to Pillow, replace winsdk (37MB monolithic binary) with lighter notification API.	2026-03-22 03:49:55 +03:00
alexei.dolgolyov	14adc8172b	perf: reduce Windows portable build size by ~80MB Some checks failed Lint & Test / test (push) Failing after 28s Details Strip unnecessary files from site-packages: - Remove pip, setuptools, pythonwin (not needed at runtime) - OpenCV: remove unused extra modules and data - numpy: remove tests, f2py, typing stubs - Remove all .dist-info directories and .pyi type stubs - Remove winsdk type stubs	2026-03-22 03:46:20 +03:00
alexei.dolgolyov	0e54616000	fix: use msiextract for tkinter, fix step numbering, graceful Docker fallback Some checks failed Build Release / create-release (push) Successful in 0s Details Lint & Test / test (push) Failing after 14s Details Build Release / build-linux (push) Successful in 1m27s Details Build Release / build-docker (push) Successful in 6s Details Build Release / build-windows (push) Successful in 3m26s Details - Replace 7z with msiextract (msitools) to extract tkinter from python.org's individual MSI packages (tcltk.msi + lib.msi) - Fix build step numbering to /9 - Docker job continues on login failure (registry may not be enabled) - Show makensis output for debugging	2026-03-22 03:44:37 +03:00
alexei.dolgolyov	3633793972	fix: extract tkinter from Python installer via 7z, fix NSIS icon path Some checks failed Build Release / create-release (push) Successful in 1s Details Lint & Test / test (push) Failing after 15s Details Build Release / build-linux (push) Successful in 1m20s Details Build Release / build-docker (push) Failing after 9s Details Build Release / build-windows (push) Successful in 3m19s Details - Replace nuget approach (doesn't contain tkinter) with extracting from the official Python amd64.exe installer using 7z - Remove MUI_ICON/MUI_UNICON (no .ico file available, use NSIS default) - Add p7zip-full to CI dependencies	2026-03-22 03:40:06 +03:00
alexei.dolgolyov	7f799a914d	feat: add NSIS Windows installer to release workflow Some checks failed Build Release / create-release (push) Successful in 1s Details Lint & Test / test (push) Failing after 15s Details Build Release / build-linux (push) Successful in 1m21s Details Build Release / build-docker (push) Failing after 9s Details Build Release / build-windows (push) Failing after 1m37s Details - installer.nsi: per-user install to AppData, Start Menu shortcuts, optional desktop shortcut and autostart, clean uninstall (preserves data/), Add/Remove Programs registration - build-dist-windows.sh: runs makensis after ZIP if available - release.yml: install nsis in CI, upload both ZIP and setup.exe - Fix Docker registry login (sed -E for https:// stripping)	2026-03-22 03:35:34 +03:00
alexei.dolgolyov	d5b5c255e8	feat: bundle tkinter into Windows portable build Some checks failed Build Release / create-release (push) Successful in 5s Details Lint & Test / test (push) Failing after 21s Details Build Release / build-linux (push) Successful in 1m7s Details Build Release / build-docker (push) Failing after 4s Details Build Release / build-windows (push) Successful in 1m50s Details Download _tkinter.pyd, tkinter package, and Tcl/Tk DLLs from the official Python nuget package and copy them into the embedded Python directory. This enables the screen overlay visualization during calibration in the portable build.	2026-03-22 03:32:02 +03:00
alexei.dolgolyov	564e4c9c9c	fix: accurate port banner and tkinter graceful fallback Some checks failed Build Release / build-linux (push) Successful in 1m24s Details Build Release / create-release (push) Successful in 1s Details Lint & Test / test (push) Failing after 13s Details Build Release / build-windows (push) Successful in 1m35s Details Build Release / build-docker (push) Failing after 9s Details - Move startup banner into main.py so it shows the actual configured port instead of a hardcoded 8080 in the launcher scripts - Wrap tkinter import in try/except so embedded Python (which lacks tkinter) logs a warning instead of crashing the overlay thread	2026-03-22 03:30:19 +03:00
alexei.dolgolyov	7c80500d48	feat: add autostart scripts and fix port configuration in launchers Some checks failed Build Release / create-release (push) Successful in 1s Details Build Release / build-windows (push) Successful in 1m16s Details Build Release / build-docker (push) Failing after 8s Details Build Release / build-linux (push) Successful in 59s Details Lint & Test / test (push) Successful in 1m52s Details Windows: install-autostart.bat (Startup folder shortcut), uninstall-autostart.bat. Linux: install-service.sh (systemd unit), uninstall-service.sh. Both launchers now use python -m wled_controller.main so port is read from config/env instead of being hardcoded to 8080.	2026-03-22 03:25:05 +03:00
alexei.dolgolyov	39e3d64654	fix: replace Docker Buildx with plain docker build/push All checks were successful Lint & Test / test (push) Successful in 1m51s Details Buildx requires container networking that fails on TrueNAS runners. Plain docker build + docker push works without Buildx setup.	2026-03-22 03:20:37 +03:00
alexei.dolgolyov	47a62b1aed	fix: add app/src to embedded Python ._pth for module discovery Some checks failed Build Release / create-release (push) Successful in 1s Details Build Release / build-windows (push) Successful in 1m14s Details Lint & Test / test (push) Successful in 1m50s Details Build Release / build-docker (push) Failing after 46s Details Build Release / build-linux (push) Successful in 1m37s Details Windows embedded Python ignores PYTHONPATH when a ._pth file exists. Add ../app/src to the ._pth so wled_controller is importable. Fixes ModuleNotFoundError on portable builds.	2026-03-22 03:14:12 +03:00
alexei.dolgolyov	62fdb093d6	feat: cross-build Windows ZIP from Linux CI runner Some checks failed Lint & Test / test (push) Successful in 1m50s Details Build Release / create-release (push) Successful in 1s Details Build Release / build-linux (push) Successful in 1m54s Details Build Release / build-windows (push) Successful in 2m0s Details Build Release / build-docker (push) Failing after 1m48s Details Replace Windows runner requirement with cross-compilation: download Windows embedded Python + win_amd64 wheels from PyPI, package into the same ZIP structure as build-dist.ps1. All 4 release jobs now run on ubuntu-latest.	2026-03-22 03:05:40 +03:00
alexei.dolgolyov	67860b02ac	feat: add Linux tarball and Docker image to release workflow All checks were successful Lint & Test / test (push) Successful in 1m53s Details Restructure release.yml into 4 jobs: - create-release: shared Gitea release with download table - build-windows: existing portable ZIP (unchanged) - build-linux: new tarball with venv + run.sh launcher - build-docker: push image to Gitea Container Registry Add build-dist.sh as Linux equivalent of build-dist.ps1. Docker tags: version + latest (stable only, no latest for alpha/beta/rc).	2026-03-22 03:00:20 +03:00