fix: remove extraneous f-string prefixes in startup banner

docs: add CI/CD context file and pre-commit lint rule
Create contexts/ci-cd.md documenting release pipeline, build scripts, CI runners, and versioning. Reference it from CLAUDE.md context table. Add mandatory pre-commit lint check rule to CLAUDE.md.
2026-03-22 13:53:30 +03:00 · 2026-03-22 13:52:47 +03:00 · 2026-03-22 13:50:46 +03:00 · 2026-03-22 13:38:15 +03:00 · 2026-03-22 13:35:01 +03:00 · 2026-03-22 03:49:55 +03:00
244 changed files with 25830 additions and 16683 deletions
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -1,31 +0,0 @@
 name: Build and Deploy
 on:
  push:
    tags:
      - 'v*'
 jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Deploy to /opt/wled-controller
        run: |
          DEPLOY_DIR=/opt/wled-controller
          # Ensure deploy directory exists
          mkdir -p "$DEPLOY_DIR/data" "$DEPLOY_DIR/logs" "$DEPLOY_DIR/config"
          # Copy server files to deploy directory
          rsync -a --delete \
            --exclude 'data/' \
            --exclude 'logs/' \
            server/ "$DEPLOY_DIR/"
          # Build and restart
          cd "$DEPLOY_DIR"
          docker compose down
          docker compose up -d --build
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -0,0 +1,263 @@
 name: Build Release
 on:
  push:
    tags:
      - '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
          # Build registry path for Docker instructions
          SERVER_HOST=$(echo "${{ gitea.server_url }}" | sed -E 's|https?://||')
          REPO=$(echo "${{ gitea.repository }}" | tr '[:upper:]' '[:lower:]')
          DOCKER_IMAGE="${SERVER_HOST}/${REPO}"
          # Build release body
          BODY=$(cat <<BODY_EOF
 ## Downloads
 | Platform | File | Description |
 |----------|------|-------------|
 | Windows (installer) | \`LedGrab-${TAG}-setup.exe\` | Install with Start Menu shortcut, optional autostart, uninstaller |
 | Windows (portable) | \`LedGrab-${TAG}-win-x64.zip\` | Unzip anywhere → run \`LedGrab.bat\` |
 | Linux | \`LedGrab-${TAG}-linux-x64.tar.gz\` | Extract → run \`./run.sh\` |
 | Docker | See below | \`docker pull\` → \`docker run\` |
 After starting, open **http://localhost:8080** in your browser.
 ### Docker
 \`\`\`bash
 docker pull ${DOCKER_IMAGE}:${TAG}
 docker run -d --name ledgrab -p 8080:8080 -v ledgrab-data:/app/data ${DOCKER_IMAGE}:${TAG}
 \`\`\`
 ### First-time setup
 1. Change the default API key in \`config/default_config.yaml\` or set \`WLED_AUTH__API_KEYS='["your-secret-key"]'\`
 2. Open http://localhost:8080 and discover your WLED devices
 3. See [INSTALLATION.md](INSTALLATION.md) for detailed configuration
 BODY_EOF
          )
          # Escape body for JSON
          BODY_JSON=$(echo "$BODY" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
          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\": $BODY_JSON,
              \"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:
    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 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 }}-linux-x64
          path: build/LedGrab-*.tar.gz
          retention-days: 90
      - name: Attach tarball to release
        env:
          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
        run: |
          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")
          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"
          echo "Uploaded: $TAR_NAME"
  # ── Docker image ───────────────────────────────────────────
  build-docker:
    needs: create-release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - 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}"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          echo "registry=$REGISTRY" >> "$GITHUB_OUTPUT"
          echo "server_host=$SERVER_HOST" >> "$GITHUB_OUTPUT"
      - 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/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -0,0 +1,38 @@
 name: Lint & Test
 on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
 jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends libportaudio2
      - name: Install dependencies
        working-directory: server
        run: |
          pip install --upgrade pip
          pip install -e ".[dev]"
      - name: Lint with ruff
        working-directory: server
        run: ruff check src/ tests/
      - name: Run tests
        working-directory: server
        run: pytest --tb=short -q
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,13 @@
 repos:
  - repo: https://github.com/psf/black
    rev: '24.10.0'
    hooks:
      - id: black
        args: [--line-length=100, --target-version=py311]
        language_version: python3.11
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--line-length=100, --target-version=py311]
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,149 +7,77 @@
 **IMPORTANT for subagents:** When spawning Agent subagents (Plan, Explore, general-purpose, etc.), always instruct them to use `ast-index` via Bash for code search instead of grep/Glob. Example: include "Use `ast-index search`, `ast-index class`, `ast-index usages` etc. via Bash for code search" in the agent prompt.
 ```bash
-# Check if available:
+ast-index search "Query"                  # Universal search
 ast-index version
 # Rebuild index (first time or after major changes):
 ast-index rebuild
 # Common commands:
 ast-index search "Query"                  # Universal search across files, symbols, modules
 ast-index class "ClassName"               # Find class/struct/interface definitions
-ast-index usages "SymbolName"             # Find all places a symbol is used
+ast-index usages "SymbolName"             # Find all usage sites
-ast-index implementations "BaseClass"     # Find all subclasses/implementations
+ast-index symbol "FunctionName"           # Find any symbol
 ast-index symbol "FunctionName"           # Find any symbol (class, function, property)
 ast-index outline "path/to/File.cpp"      # Show all symbols in a file
 ast-index hierarchy "ClassName"           # Show inheritance tree
 ast-index callers "FunctionName"          # Find all call sites
 ast-index outline "path/to/File.py"       # Show all symbols in a file
 ast-index changed --base master           # Show symbols changed in current branch
 ast-index update                          # Incremental update after file changes
 ```
-## CRITICAL: Git Commit and Push Policy
+## Git Commit and Push Policy
-**🚨 NEVER CREATE COMMITS WITHOUT EXPLICIT USER APPROVAL 🚨**
+**NEVER commit or push without explicit user approval.** Wait for the user to review changes and explicitly say "commit" or "push". Completing a task, "looks good", or "thanks" do NOT count as approval. See the system-level instructions for the full commit workflow.
-**🚨 NEVER PUSH TO REMOTE WITHOUT EXPLICIT USER APPROVAL 🚨**
+## Auto-Restart and Rebuild Policy
-### Strict Rules
+- **Python code changes** (`server/src/` excluding `static/`): Auto-restart the server. See [contexts/server-operations.md](contexts/server-operations.md) for the restart procedure.
-
+- **Frontend changes** (`static/js/`, `static/css/`): Run `cd server && npm run build` to rebuild the bundle. No server restart needed.
 1. **DO NOT** create commits automatically after making changes
 2. **DO NOT** commit without being explicitly instructed by the user
 3. **DO NOT** push to remote repository without explicit instruction
 4. **ALWAYS WAIT** for the user to review changes and ask you to commit
 5. **ALWAYS ASK** if you're unsure whether to commit
 ### Workflow
 1. Make code changes as requested
 2. **STOP** - Inform user that changes are complete
 3. **WAIT** - User reviews the changes
 4. **ONLY IF** user explicitly says "commit" or "create a commit":
   - Stage the files with `git add`
   - Create the commit with a descriptive message
   - **STOP** - Do NOT push
 5. **ONLY IF** user explicitly says "push" or "commit and push":
   - Push to remote repository
 ### What Counts as Explicit Approval
 ✅ **YES - These mean you can commit:**
 - "commit"
 - "create a commit"
 - "commit these changes"
 - "git commit"
 ✅ **YES - These mean you can push:**
 - "push"
 - "commit and push"
 - "push to remote"
 - "git push"
 ❌ **NO - These do NOT mean you should commit:**
 - "that looks good"
 - "thanks"
 - "perfect"
 - User silence after you make changes
 - Completing a feature/fix
 ### Example Bad Behavior (DON'T DO THIS)
 ```
 ❌ User: "Fix the MSS engine test issue"
 ❌ Claude: [fixes the issue]
 ❌ Claude: [automatically commits without asking]  <-- WRONG!
 ```
 ### Example Good Behavior (DO THIS)
 ```
 ✅ User: "Fix the MSS engine test issue"
 ✅ Claude: [fixes the issue]
 ✅ Claude: "I've fixed the MSS engine test issue by adding auto-initialization..."
 ✅ [WAITS FOR USER]
 ✅ User: "Looks good, commit it"
 ✅ Claude: [now creates the commit]
 ```
 ## IMPORTANT: Auto-Restart Server on Code Changes
 **Whenever server-side Python code is modified** (any file under `/server/src/` **excluding** `/server/src/wled_controller/static/`), **automatically restart the server** so the changes take effect immediately. Do NOT wait for the user to ask for a restart.
 **No restart needed for frontend-only changes** — but you **MUST rebuild the bundle**. The browser loads the esbuild bundle (`static/dist/app.bundle.js`, `static/dist/app.bundle.css`), NOT the source files. After ANY change to frontend files (JS, CSS under `/server/src/wled_controller/static/`), run:
 ```bash
 cd server && npm run build
 ```
 Without this step, changes will NOT take effect. No server restart is needed — just rebuild and refresh the browser.
 ### Restart procedure
 Use the PowerShell restart script — it reliably stops only the server process and starts a new detached instance:
 ```bash
 powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\wled-screen-controller\server\restart.ps1"
 ```
 **Do NOT use** `Stop-Process -Name python` (kills unrelated Python processes like VS Code extensions) or bash background `&` jobs (get killed when the shell session ends).
 ## Default Config & API Key
 The server configuration is in `/server/config/default_config.yaml`. The default API key for development is `development-key-change-in-production` (label: `dev`). The server runs on port **8080** by default.
 ## Project Structure
-This is a monorepo containing:
+- `/server` — Python FastAPI backend (see [server/CLAUDE.md](server/CLAUDE.md))
- `/server` - Python FastAPI backend (see `server/CLAUDE.md` for detailed instructions)
+- `/contexts` — Context files for Claude (frontend conventions, graph editor, Chrome tools, server ops, demo mode)
 - `/client` - Future frontend client (if applicable)
-## Working with Server
+## Context Files
-For detailed server-specific instructions (restart policy, testing, etc.), see:
+| File | When to read |
- `server/CLAUDE.md`
+| ---- | ------------ |
-
+| [contexts/frontend.md](contexts/frontend.md) | HTML, CSS, JS/TS, i18n, modals, icons, bundling |
-## Frontend (HTML, CSS, JS, i18n)
+| [contexts/graph-editor.md](contexts/graph-editor.md) | Visual graph editor changes |
-
+| [contexts/server-operations.md](contexts/server-operations.md) | Server restart, startup modes, demo mode |
-For all frontend conventions (CSS variables, UI patterns, modals, localization, tutorials), see [`contexts/frontend.md`](contexts/frontend.md).
+| [contexts/chrome-tools.md](contexts/chrome-tools.md) | Chrome MCP tool usage for testing |
 | [contexts/ci-cd.md](contexts/ci-cd.md) | CI/CD pipelines, release workflow, build scripts |
 | [server/CLAUDE.md](server/CLAUDE.md) | Backend architecture, API patterns, common tasks |
 ## Task Tracking via TODO.md
 Use `TODO.md` in the project root as the primary task tracker. **Do NOT use the TodoWrite tool** — all progress tracking goes through `TODO.md`.
 - **When starting a multi-step task**: add sub-steps as `- [ ]` items under the relevant section
 - **When completing a step**: mark it `- [x]` immediately — don't batch updates
 - **When a task is fully done**: mark it `- [x]` and leave it for the user to clean up
 - **When the user requests a new feature/fix**: add it to the appropriate section with a priority tag
 ## Documentation Lookup
-**Use context7 MCP tools for library/framework documentation lookups.** When you need to check API signatures, usage patterns, or current behavior of external libraries (e.g., FastAPI, OpenCV, Pydantic, yt-dlp), use `mcp__plugin_context7_context7__resolve-library-id` to find the library, then `mcp__plugin_context7_context7__query-docs` to fetch up-to-date docs. This avoids relying on potentially outdated training data.
+**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.
 ## Pre-Commit Checks (MANDATORY)
 Before every commit, run the relevant linters and fix any issues:
 - **Python changes**: `cd server && ruff check src/ tests/ --fix`
 - **TypeScript changes**: `cd server && npx tsc --noEmit && npm run build`
 - **Both**: Run both checks
 Do NOT commit code that fails linting. Fix the issues first.
 ## General Guidelines
 - Always test changes before marking as complete
 - Follow existing code style and patterns
 - Update documentation when changing behavior
 - Write clear, descriptive commit messages when explicitly instructed
 - Never make commits or pushes without explicit user approval
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,85 @@
 # Contributing
 ## Prerequisites
 - Python 3.11+
 - Node.js 20+ (for frontend bundle)
 - Git
 ## Development Setup
 ```bash
 git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
 cd wled-screen-controller-mixed/server
 # Python environment
 python -m venv venv
 source venv/bin/activate   # Linux/Mac
 # venv\Scripts\activate    # Windows
 pip install -e ".[dev]"
 # Frontend dependencies
 npm install
 npm run build
 ```
 ## Running the Server
 ```bash
 cd server
 export PYTHONPATH=$(pwd)/src   # Linux/Mac
 # set PYTHONPATH=%CD%\src      # Windows
 python -m wled_controller.main
 ```
 Open http://localhost:8080 to access the dashboard.
 ## Running Tests
 ```bash
 cd server
 pytest
 ```
 Tests use pytest with pytest-asyncio. Coverage reports are generated automatically.
 ## Code Style
 This project uses **black** for formatting and **ruff** for linting (both configured in `pyproject.toml` with a line length of 100).
 ```bash
 cd server
 black src/ tests/
 ruff check src/ tests/
 ```
 ## Frontend Changes
 After modifying any file under `server/src/wled_controller/static/js/` or `static/css/`, rebuild the bundle:
 ```bash
 cd server
 npm run build
 ```
 The browser loads the esbuild bundle (`static/dist/`), not the source files directly.
 ## Commit Messages
 Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
 ```
 feat: add new capture engine
 fix: correct LED color mapping
 refactor: extract filter pipeline
 docs: update API reference
 test: add audio source tests
 chore: update dependencies
 ```
 ## Pull Requests
 1. Create a feature branch from `master`
 2. Make your changes with tests
 3. Ensure `ruff check` and `pytest` pass
 4. Open a PR with a clear description of the change
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -1,281 +1,222 @@
 # Installation Guide
-Complete installation guide for WLED Screen Controller server and Home Assistant integration.
+Complete installation guide for LED Grab (WLED Screen Controller) server and Home Assistant integration.
 ## Table of Contents
-1. [Server Installation](#server-installation)
+1. [Docker Installation (recommended)](#docker-installation)
-2. [Home Assistant Integration](#home-assistant-integration)
+2. [Manual Installation](#manual-installation)
-3. [Quick Start](#quick-start)
+3. [First-Time Setup](#first-time-setup)
 4. [Home Assistant Integration](#home-assistant-integration)
 5. [Configuration Reference](#configuration-reference)
 6. [Troubleshooting](#troubleshooting)
 ---
-## Server Installation
+## Docker Installation
-### Option 1: Python (Development/Testing)
+The fastest way to get running. Requires [Docker](https://docs.docker.com/get-docker/) with Compose.
-**Requirements:**
+1. **Clone and start:**
 - Python 3.11 or higher
 - Windows, Linux, or macOS
-**Steps:**
+   ```bash
   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   docker compose up -d
   ```
 2. **Verify:**
   ```bash
   curl http://localhost:8080/health
   # → {"status":"healthy", ...}
   ```
 3. **Open the dashboard:** <http://localhost:8080>
 4. **View logs:**
   ```bash
   docker compose logs -f
   ```
 5. **Stop / restart:**
   ```bash
   docker compose down          # stop
   docker compose up -d         # start again (data is persisted)
   ```
 ### Docker manual build (without Compose)
 ```bash
 cd server
 docker build -t ledgrab .
 docker run -d \
  --name wled-screen-controller \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/config:/app/config:ro \
  ledgrab
 ```
 ### Linux screen capture in Docker
 Screen capture from inside a container requires X11 access. Uncomment `network_mode: host` in `docker-compose.yml` and ensure the `DISPLAY` variable is set. Wayland is not currently supported for in-container capture.
 ---
 ## Manual Installation
 ### Requirements
 | Dependency | Version | Purpose |
 | ---------- | ------- | ------- |
 | Python | 3.11+ | Backend server |
 | Node.js | 18+ | Frontend build (esbuild) |
 | pip | latest | Python package installer |
 | npm | latest | Node package manager |
 ### Steps
 1. **Clone the repository:**
   ```bash
-   git clone https://github.com/yourusername/wled-screen-controller.git
+   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   ```
-2. **Create virtual environment:**
+2. **Build the frontend bundle:**
   ```bash
   npm ci
   npm run build
   ```
   This compiles TypeScript and bundles JS/CSS into `src/wled_controller/static/dist/`.
 3. **Create a virtual environment:**
   ```bash
   python -m venv venv
-   # Windows
+   # Linux / macOS
   source venv/bin/activate
   # Windows (cmd)
   venv\Scripts\activate
-   # Linux/Mac
+   # Windows (PowerShell)
-   source venv/bin/activate
+   venv\Scripts\Activate.ps1
   ```
-3. **Install dependencies:**
+4. **Install Python dependencies:**
   ```bash
   pip install .
   ```
-4. **Configure (optional):**
+   Optional extras:
   Edit `config/default_config.yaml` to customize settings.
 5. **Run the server:**
   ```bash
-   # Set PYTHONPATH
+   pip install ".[camera]"          # Webcam capture via OpenCV
-   export PYTHONPATH=$(pwd)/src  # Linux/Mac
+   pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
-   set PYTHONPATH=%CD%\src        # Windows
+   pip install ".[notifications]"   # OS notification capture
   pip install ".[dev]"             # pytest, black, ruff (development)
   ```
-   # Start server
+5. **Set PYTHONPATH and start the server:**
   ```bash
   # Linux / macOS
   export PYTHONPATH=$(pwd)/src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   # Windows (cmd)
   set PYTHONPATH=%CD%\src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   ```
-6. **Verify:**
+6. **Verify:** open <http://localhost:8080> in your browser.
   Open http://localhost:8080/docs in your browser.
-### Option 2: Docker (Recommended for Production)
+---
-**Requirements:**
+## First-Time Setup
 - Docker
 - Docker Compose
-**Steps:**
+### Change the default API key
-1. **Clone the repository:**
+The server ships with a development API key (`development-key-change-in-production`). **Change it before exposing the server on your network.**
-   ```bash
+
-   git clone https://github.com/yourusername/wled-screen-controller.git
+Option A -- edit the config file:
-   cd wled-screen-controller/server
+
 ```yaml
 # server/config/default_config.yaml
 auth:
  api_keys:
    main: "your-secure-key-here"   # replace the dev key
 ```
-2. **Start with Docker Compose:**
+Option B -- set an environment variable:
   ```bash
   docker-compose up -d
   ```
 3. **View logs:**
   ```bash
   docker-compose logs -f
   ```
 4. **Verify:**
   Open http://localhost:8080/docs in your browser.
 ### Option 3: Docker (Manual Build)
 ```bash
-cd server
+export WLED_AUTH__API_KEYS__main="your-secure-key-here"
 docker build -t wled-screen-controller .
 docker run -d \
  --name wled-controller \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  --network host \
  wled-screen-controller
 ```
 Generate a random key:
 ```bash
 openssl rand -hex 32
 ```
 ### Configure CORS for LAN access
 By default the server only allows requests from `http://localhost:8080`. To access the dashboard from another machine on your LAN, add its origin:
 ```yaml
 # server/config/default_config.yaml
 server:
  cors_origins:
    - "http://localhost:8080"
    - "http://192.168.1.100:8080"   # your server's LAN IP
 ```
 Or via environment variable:
 ```bash
 WLED_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
 ```
 ### Discover devices
 Open the dashboard and go to the **Devices** tab. Click **Discover** to find WLED devices on your network via mDNS. You can also add devices manually by IP address.
 ---
 ## Home Assistant Integration
-### Option 1: HACS (Recommended)
+### Option 1: HACS (recommended)
-1. **Install HACS** if not already installed:
+1. Install [HACS](https://hacs.xyz/docs/setup/download) if you have not already.
-   - Follow instructions at https://hacs.xyz/docs/setup/download
+2. Open HACS in Home Assistant.
 3. Click the three-dot menu, then **Custom repositories**.
 4. Add URL: `https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed`
 5. Set category to **Integration** and click **Add**.
 6. Search for "WLED Screen Controller" in HACS and click **Download**.
 7. Restart Home Assistant.
 8. Go to **Settings > Devices & Services > Add Integration** and search for "WLED Screen Controller".
 9. Enter your server URL (e.g., `http://192.168.1.100:8080`) and API key.
-2. **Add Custom Repository:**
+### Option 2: Manual
   - Open HACS in Home Assistant
   - Click the three dots menu → Custom repositories
   - Add URL: `https://github.com/yourusername/wled-screen-controller`
   - Category: Integration
   - Click Add
-3. **Install Integration:**
+Copy the `custom_components/wled_screen_controller/` folder from this repository into your Home Assistant `config/custom_components/` directory, then restart Home Assistant and add the integration as above.
   - In HACS, search for "WLED Screen Controller"
   - Click Download
   - Restart Home Assistant
-4. **Configure Integration:**
+### Automation example
   - Go to Settings → Devices & Services
   - Click "+ Add Integration"
   - Search for "WLED Screen Controller"
   - Enter your server URL (e.g., `http://192.168.1.100:8080`)
   - Click Submit
 ### Option 2: Manual Installation
 1. **Download Integration:**
   ```bash
   cd /config  # Your Home Assistant config directory
   mkdir -p custom_components
   ```
 2. **Copy Files:**
   Copy the `custom_components/wled_screen_controller` folder to your Home Assistant `custom_components` directory.
 3. **Restart Home Assistant**
 4. **Configure Integration:**
   - Go to Settings → Devices & Services
   - Click "+ Add Integration"
   - Search for "WLED Screen Controller"
   - Enter your server URL
   - Click Submit
 ---
 ## Quick Start
 ### 1. Start the Server
 ```bash
 cd wled-screen-controller/server
 docker-compose up -d
 ```
 ### 2. Attach Your WLED Device
 ```bash
 curl -X POST http://localhost:8080/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Living Room TV",
    "url": "http://192.168.1.100",
    "led_count": 150
  }'
 ```
 ### 3. Configure in Home Assistant
 1. Add the integration (see above)
 2. Your WLED devices will appear automatically
 3. Use the switch to turn processing on/off
 4. Use the select to choose display
 5. Monitor FPS and status via sensors
 ### 4. Start Processing
 Either via API:
 ```bash
 curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
 ```
 Or via Home Assistant:
 - Turn on the "{Device Name} Processing" switch
 ### 5. Enjoy Ambient Lighting!
 Your WLED strip should now sync with your screen content!
 ---
 ## Troubleshooting
 ### Server Won't Start
 **Check Python version:**
 ```bash
 python --version  # Should be 3.11+
 ```
 **Check dependencies:**
 ```bash
 pip list | grep fastapi
 ```
 **Check logs:**
 ```bash
 # Docker
 docker-compose logs -f
 # Python
 tail -f logs/wled_controller.log
 ```
 ### Home Assistant Integration Not Appearing
 1. Check HACS installation
 2. Clear browser cache
 3. Restart Home Assistant
 4. Check Home Assistant logs:
   - Settings → System → Logs
   - Search for "wled_screen_controller"
 ### Can't Connect to Server from Home Assistant
 1. Verify server is running:
   ```bash
   curl http://YOUR_SERVER_IP:8080/health
   ```
 2. Check firewall rules
 3. Ensure Home Assistant can reach server IP
 4. Try http:// not https://
 ### WLED Device Not Responding
 1. Check WLED device is powered on
 2. Verify IP address is correct
 3. Test WLED directly:
   ```bash
   curl http://YOUR_WLED_IP/json/info
   ```
 4. Check network connectivity
 ### Low FPS / Performance Issues
 1. Reduce target FPS (Settings → Devices)
 2. Reduce `border_width` in settings
 3. Check CPU usage on server
 4. Consider reducing LED count
 ---
 ## Configuration Examples
 ### Server Environment Variables
 ```bash
 # Docker .env file
 WLED_SERVER__HOST=0.0.0.0
 WLED_SERVER__PORT=8080
 WLED_SERVER__LOG_LEVEL=INFO
 WLED_PROCESSING__DEFAULT_FPS=30
 WLED_PROCESSING__BORDER_WIDTH=10
 ```
 ### Home Assistant Automation Example
 ```yaml
 automation:
-  - alias: "Auto Start WLED on TV On"
+  - alias: "Start ambient lighting when TV turns on"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
@@ -285,7 +226,7 @@ automation:
        target:
          entity_id: switch.living_room_tv_processing
-  - alias: "Auto Stop WLED on TV Off"
+  - alias: "Stop ambient lighting when TV turns off"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
@@ -298,8 +239,89 @@ automation:
 ---
 ## Configuration Reference
 The server reads configuration from three sources (in order of priority):
 1. **Environment variables** -- prefix `WLED_`, double underscore as nesting delimiter (e.g., `WLED_SERVER__PORT=9090`)
 2. **YAML config file** -- `server/config/default_config.yaml` (or set `WLED_CONFIG_PATH` to override)
 3. **Built-in defaults**
 See [`server/.env.example`](server/.env.example) for every available variable with descriptions.
 ### Key settings
 | Variable | Default | Description |
 | -------- | ------- | ----------- |
 | `WLED_SERVER__PORT` | `8080` | HTTP listen port |
 | `WLED_SERVER__LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `WLED_SERVER__CORS_ORIGINS` | `["http://localhost:8080"]` | Allowed CORS origins (JSON array) |
 | `WLED_AUTH__API_KEYS` | `{"dev":"development-key..."}` | API keys (JSON object) |
 | `WLED_MQTT__ENABLED` | `false` | Enable MQTT for HA auto-discovery |
 | `WLED_MQTT__BROKER_HOST` | `localhost` | MQTT broker address |
 | `WLED_DEMO` | `false` | Enable demo mode (sandbox with virtual devices) |
 ---
 ## Troubleshooting
 ### Server will not start
 **Check Python version:**
 ```bash
 python --version  # must be 3.11+
 ```
 **Check the frontend bundle exists:**
 ```bash
 ls server/src/wled_controller/static/dist/app.bundle.js
 ```
 If missing, run `cd server && npm ci && npm run build`.
 **Check logs:**
 ```bash
 # Docker
 docker compose logs -f
 # Manual install
 tail -f logs/wled_controller.log
 ```
 ### Cannot access the dashboard from another machine
 1. Verify the server is reachable: `curl http://SERVER_IP:8080/health`
 2. Check your firewall allows inbound traffic on port 8080.
 3. Add your server's LAN IP to `cors_origins` (see [Configure CORS](#configure-cors-for-lan-access) above).
 ### Home Assistant integration not appearing
 1. Verify HACS installed the component: check that `config/custom_components/wled_screen_controller/` exists.
 2. Clear your browser cache.
 3. Restart Home Assistant.
 4. Check logs at **Settings > System > Logs** and search for `wled_screen_controller`.
 ### WLED device not responding
 1. Confirm the device is powered on and connected to Wi-Fi.
 2. Test it directly: `curl http://DEVICE_IP/json/info`
 3. Check that the server and the device are on the same subnet.
 4. Try restarting the WLED device.
 ### Low FPS or high latency
 1. Lower the target FPS in the stream settings.
 2. Reduce `border_width` to decrease the number of sampled pixels.
 3. Check CPU usage on the server (`htop` or Task Manager).
 4. On Windows, install the `perf` extra for GPU-accelerated capture: `pip install ".[perf]"`
 ---
 ## Next Steps
 - [API Documentation](docs/API.md)
 - [Calibration Guide](docs/CALIBRATION.md)
- [GitHub Issues](https://github.com/yourusername/wled-screen-controller/issues)
+- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues)
--- a/README.md
+++ b/README.md
@@ -84,26 +84,42 @@ A Home Assistant integration exposes devices as entities for smart home automati
 ## Quick Start
 ### Docker (recommended)
 ```bash
-git clone https://github.com/yourusername/wled-screen-controller.git
+git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
 cd wled-screen-controller/server
 docker compose up -d
 ```
 ### Manual
 Requires Python 3.11+ and Node.js 18+.
 ```bash
 git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
 cd wled-screen-controller/server
-# Option A: Docker (recommended)
+# Build the frontend bundle
-docker-compose up -d
+npm ci && npm run build
-# Option B: Python
+# Create a virtual environment and install
 python -m venv venv
 source venv/bin/activate        # Linux/Mac
 # venv\Scripts\activate         # Windows
 pip install .
 # Start the server
 export PYTHONPATH=$(pwd)/src    # Linux/Mac
 # set PYTHONPATH=%CD%\src       # Windows
 uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
 ```
-Open `http://localhost:8080` to access the dashboard. The default API key for development is `development-key-change-in-production`.
+Open **http://localhost:8080** to access the dashboard.
-See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including Docker manual builds and Home Assistant setup.
+> **Important:** The default API key is `development-key-change-in-production`. Change it before exposing the server outside localhost. See [INSTALLATION.md](INSTALLATION.md) for details.
 See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and Home Assistant setup.
 ## Architecture
@@ -146,7 +162,7 @@ wled-screen-controller/
 ## Configuration
-Edit `server/config/default_config.yaml` or use environment variables with the `LED_GRAB_` prefix:
+Edit `server/config/default_config.yaml` or use environment variables with the `WLED_` prefix:
 ```yaml
 server:
@@ -168,7 +184,7 @@ logging:
  max_size_mb: 100
 ```
-Environment variable override example: `LED_GRAB_SERVER__PORT=9090`.
+Environment variable override example: `WLED_SERVER__PORT=9090`.
 ## API
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -1,138 +0,0 @@
 # Codebase Review Report
 _Generated 2026-03-09_
 ---
 ## 1. Bugs (Critical)
 ### Thread Safety / Race Conditions
 | Issue | Location | Description |
 |-------|----------|-------------|
 | **Dict mutation during iteration** | `composite_stream.py:121`, `mapped_stream.py:102` | `update_source()` calls `_sub_streams.clear()` from the API thread while `_processing_loop` iterates the dict on a background thread. **Will crash with `RuntimeError: dictionary changed size during iteration`.** |
 | **Clock ref-count corruption** | `color_strip_stream_manager.py:286-304` | On clock hot-swap, `_release_clock` reads the *new* clock_id from the store (already updated), so it releases the newly acquired clock instead of the old one. Leaks the old runtime, destroys the new one. |
 | **SyncClockRuntime race** | `sync_clock_runtime.py:42-49` | `get_time()` reads `_running`, `_offset`, `_epoch` without `_lock`, while `pause()`/`resume()`/`reset()` modify them under `_lock`. Compound read can double-count elapsed time. |
 | **SyncClockManager unprotected dicts** | `sync_clock_manager.py:26-54` | `_runtimes` and `_ref_counts` are plain dicts mutated from both the async event loop and background threads with no lock. |
 ### Silent Failures
 | Issue | Location | Description |
 |-------|----------|-------------|
 | **Crashed streams go undetected** | `mapped_stream.py:214`, `composite_stream.py` | When the processing loop dies, `get_latest_colors()` permanently returns stale data. The target keeps sending frozen colors to LEDs with no indicator anything is wrong. |
 | **Crash doesn't fire state_change event** | `wled_target_processor.py:900` | Fatal exception path sets `_is_running = False` without firing `state_change` event (only `stop()` fires it). Dashboard doesn't learn about crashes via WebSocket. |
 | **WebSocket broadcast client mismatch** | `kc_target_processor.py:481-485` | `zip(self._ws_clients, results)` pairs results with the live list, but clients can be removed between scheduling `gather` and collecting results, causing wrong clients to be dropped. |
 ### Security
 | Issue | Location | Description |
 |-------|----------|-------------|
 | **Incomplete path traversal guard** | `auto_backup.py` | Filename validation uses string checks (`".." in filename`) instead of `Path.resolve().is_relative_to()`. |
 ---
 ## 2. Performance
 ### High Impact (Hot Path)
 | Issue | Location | Impact |
 |-------|----------|--------|
 | **Per-frame `np.array()` from list** | `ddp_client.py:195` | Allocates a new numpy array from a Python list every frame. Should use pre-allocated buffer. |
 | **Triple FFT for mono audio** | `analysis.py:168-174` | When audio is mono (common for system loopback), runs 3 identical FFTs. 2x wasted CPU. |
 | **`frame_time = 1.0/fps` in every loop iteration** | 8 stream files | Recomputed every frame despite `_fps` only changing on consumer subscribe. Should be cached. |
 | **4x deque traversals per frame for metrics** | `kc_target_processor.py:413-416` | Full traversal of metrics deques every frame to compute avg/min/max. |
 | **3x spectrum `.copy()` per audio chunk** | `analysis.py:195-201` | ~258 array allocations/sec for read-only consumers. Could use non-writable views. |
 ### Medium Impact
 | Issue | Location |
 |-------|----------|
 | `getattr` + dict lookup per composite layer per frame | `composite_stream.py:299-304` |
 | Unconditional `self.*=` attribute writes every frame in audio stream | `audio_stream.py:255-261` |
 | `JSON.parse(localStorage)` on every collapsed-section call | `dashboard.js` `_getCollapsedSections` |
 | Effect/composite/mapped streams hardcoded to 30 FPS | `effect_stream.py`, `composite_stream.py:37`, `mapped_stream.py:33` |
 | Double `querySelectorAll` on card reconcile | `card-sections.js:229-232` |
 | Module import inside per-second sampling function | `metrics_history.py:21,35` |
 | `datetime.utcnow()` twice per frame | `kc_target_processor.py:420,464` |
 | Redundant `bytes()` copy of bytes slice | `ddp_client.py:222` |
 | Unnecessary `.copy()` of temp interp result | `audio_stream.py:331,342` |
 | Multiple intermediate numpy allocs for luminance | `value_stream.py:486-494` |
 ---
 ## 3. Code Quality
 ### Architecture
 | Issue | Description |
 |-------|-------------|
 | **12 store classes with duplicated boilerplate** | All JSON stores repeat the same load/save/CRUD pattern with no base class. A `BaseJsonStore[T]` would eliminate ~60% of each store file. |
 | **`DeviceStore.save()` uses unsafe temp file** | Fixed-path temp file instead of `atomic_write_json` used by all other stores. |
 | **`scene_activator.py` accesses `ProcessorManager._processors` directly** | Lines 33, 68, 90, 110 — bypasses public API, breaks encapsulation. |
 | **Route code directly mutates `ProcessorManager` internals** | `devices.py` accesses `manager._devices` and `manager._color_strip_stream_manager` in 13+ places. |
 | **`color-strips.js` is 1900+ lines** | Handles 11 CSS source types, gradient editor, composite layers, mapped zones, card rendering, overlay control — should be split. |
 | **No `DataCache` for color strip sources** | Every other entity uses `DataCache`. CSS sources are fetched with raw `fetchWithAuth` in 5+ places with no deduplication. |
 ### Consistency / Hygiene
 | Issue | Location |
 |-------|----------|
 | `Dict[str, any]` (lowercase `any`) — invalid type annotation | `template_store.py:138,187`, `audio_template_store.py:126,155` |
 | `datetime.utcnow()` deprecated — 88 call sites in 42 files | Project-wide |
 | `_icon` SVG helper duplicated verbatim in 3 JS files | `color-strips.js:293`, `automations.js:41`, `kc-targets.js:49` |
 | `hexToRgbArray` private to one file, pattern inlined elsewhere | `color-strips.js:471` vs line 1403 |
 | Hardcoded English fallback in `showToast` | `color-strips.js:1593` |
 | `ColorStripStore.create_source` silently creates wrong type for unknown `source_type` | `color_strip_store.py:92-332` |
 | `update_source` clock_id clearing uses undocumented empty-string sentinel | `color_strip_store.py:394-395` |
 | `DeviceStore._load` lacks per-item error isolation (unlike all other stores) | `device_store.py:122-138` |
 | No unit tests | Zero test files. Highest-risk: `CalibrationConfig`/`PixelMapper` geometry, DDP packets, automation conditions. |
 ---
 ## 4. Features & Suggestions
 ### High Impact / Low Effort
 | Suggestion | Details |
 |------------|---------|
 | **Auto-restart crashed processing loops** | Add backoff-based restart when `_processing_loop` dies. Currently crashes are permanent until manual intervention. |
 | **Fire `state_change` on crash** | Add `finally` block in `_processing_loop` to notify the dashboard immediately. |
 | **`POST /system/auto-backup/trigger`** | ~5 lines of Python. Manual backup trigger before risky config changes. |
 | **`is_healthy` property on streams** | Let target processors detect when their color source has died. |
 | **Rotate webhook token endpoint** | `POST /automations/{id}/rotate-webhook-token` — regenerate without recreating automation. |
 | **"Start All" targets button** | "Stop All" exists but "Start All" (the more common operation after restart) is missing. |
 | **Include auto-backup settings in backup** | Currently lost on restore. |
 | **Distinguish "crashed" vs "stopped" in dashboard** | `metrics.last_error` is already populated — just surface it. |
 ### High Impact / Moderate Effort
 | Suggestion | Details |
 |------------|---------|
 | **Home Assistant MQTT discovery** | Publish auto-discovery payloads so devices appear in HA automatically. MQTT infra already exists. |
 | **Device health WebSocket events** | Eliminates 5-30s poll latency for online/offline detection. |
 | **`GET /system/store-errors`** | Surface startup deserialization failures to the user. Currently only in logs. |
 | **Scene snapshot should capture device brightness** | `software_brightness` is not saved/restored by scenes. |
 | **Exponential backoff on events WebSocket reconnect** | Currently fixed 3s retry, generates constant logs during outages. |
 | **CSS source import/export** | Share individual sources without full config backup. |
 | **Per-target error ring buffer via API** | `GET /targets/{id}/logs` for remote debugging. |
 | **DDP socket reconnection** | UDP socket invalidated on network changes; no reconnect path exists. |
 | **Adalight serial reconnection** | COM port disconnect crashes the target permanently. |
 | **MQTT-controlled brightness and scene activation** | Direct command handler without requiring API key management. |
 ### Nice-to-Have
 | Suggestion | Details |
 |------------|---------|
 | Configurable metrics history window (currently hardcoded 120 samples / 2 min) | |
 | Replace `window.prompt()` API key entry with proper modal | |
 | Pattern template live preview (SVG/Canvas) | |
 | Keyboard shortcuts for start/stop targets and scene activation | |
 | FPS chart auto-scaling y-axis (`Math.max(target*1.15, maxSeen*1.1)`) | |
 | WLED native preset target type (send `{"ps": id}` instead of pixels) | |
 | Configurable DDP max packet size per device | |
 | `GET /system/active-streams` unified runtime snapshot | |
 | OpenMetrics / Prometheus endpoint for Grafana integration | |
 | Configurable health check intervals (currently hardcoded 10s/60s) | |
 | Configurable backup directory path | |
 | `GET /system/logs?tail=100&level=ERROR` for in-app log viewing | |
 | Device card "currently streaming" badge | |
--- a/TODO.md
+++ b/TODO.md
@@ -1,129 +0,0 @@
 # Pending Features & Issues
 Priority: `P1` quick win · `P2` moderate · `P3` large effort
 ## Processing Pipeline
 - [ ] `P3` **Transition effects** — Crossfade, wipe, or dissolve between sources/profiles instead of instant cut
  - Complexity: large — requires a new transition layer concept in ProcessorManager; must blend two live streams simultaneously during switch, coordinating start/stop timing
  - Impact: medium — polishes profile switching UX but ambient lighting rarely switches sources frequently
 ## Output Targets
 - [ ] `P2` **Art-Net / sACN (E1.31)** — Stage/theatrical lighting protocols, DMX controllers
  - Complexity: medium — UDP-based protocols with well-documented specs; similar architecture to DDP client; needs DMX universe/channel mapping UI
  - Impact: medium — opens stage/theatrical use case, niche but differentiating
 ## Capture Engines
 - [ ] `P3` **SCRCPY capture engine** — Implement SCRCPY-based screen capture for Android devices
  - Complexity: large — external dependency on scrcpy binary; need to manage subprocess lifecycle, parse video stream (ffmpeg/AV pipe), handle device connect/disconnect
  - Impact: medium — enables phone screen mirroring to ambient lighting; appeals to mobile gaming use case
 ## Code Health
 - [ ] `P1` **"Start All" targets button** — "Stop All" exists but "Start All" is missing
 - [x] `P2` **Manual backup trigger endpoint** — `POST /system/auto-backup/trigger` (~5 lines)
 - [ ] `P2` **Scene snapshot should capture device brightness** — `software_brightness` not saved/restored
 - [ ] `P2` **Distinguish "crashed" vs "stopped" in dashboard** — `metrics.last_error` is already populated
 - [ ] `P3` **CSS source import/export** — share individual sources without full config backup
 ## Backend Review Fixes (2026-03-14)
 ### Performance
 - [x] **P1** PIL blocking in async handlers → `asyncio.to_thread`
 - [x] **P2** `subprocess.run` blocking event loop → `asyncio.create_subprocess_exec`
 - [x] **P3** Audio enum blocking async → `asyncio.to_thread`
 - [x] **P4** Display enum blocking async → `asyncio.to_thread`
 - [x] **P5** `colorsys` scalar loop in hot path → vectorize numpy
 - [x] **P6** `MappedStream` per-frame allocation → double-buffer
 - [x] **P7** Audio/effect per-frame temp allocs → pre-allocate
 - [x] **P8** Blocking `httpx.get` in stream init → documented (callers use to_thread)
 - [x] **P9** No-cache middleware runs on all requests → scope to static
 - [x] **P10** Sync file I/O in async handlers (stores) → documented as accepted risk (< 5ms)
 - [x] **P11** `frame_time` float division every loop iter → cache field
 - [x] **P12** `_check_name_unique` O(N) + no lock → add threading.Lock
 - [x] **P13** Imports inside 1-Hz metrics loop → move to module level
 ### Code Quality
 - [x] **Q1** `DeviceStore` not using `BaseJsonStore`
 - [x] **Q2** `ColorStripStore` 275-line god methods → factory dispatch
 - [x] **Q3** Layer violation: core imports from routes → extract to utility
 - [x] **Q4** 20+ field-by-field update in Device/routes → dataclass + generic update
 - [x] **Q5** WebSocket auth copy-pasted 9x → extract helper
 - [x] **Q6** `set_device_brightness` bypasses store → use update_device
 - [x] **Q7** DI via 16+ module globals → registry pattern
 - [x] **Q8** `_css_to_response` 30+ getattr → polymorphic to_response
 - [x] **Q9** Private attribute access across modules → expose as properties
 - [x] **Q10** `ColorStripSource.to_dict()` emits ~25 nulls → per-subclass override
 - [x] **Q11** `DeviceStore.get_device` returns None vs raises → raise ValueError
 - [x] **Q12** `list_all_tags` fragile method-name probing → use get_all()
 - [x] **Q13** Route create/update pass 30 individual fields → **kwargs
 ## UX
 - [ ] `P1` **Collapse dashboard running target stats** — Show only FPS chart by default; uptime, errors, and pipeline timings in an expandable section collapsed by default
 - [x] `P1` **Daylight brightness value source** — New value source type that reports a 0–255 brightness level based on daylight cycle time (real-time or simulated), reusing the daylight LUT logic
 - [x] `P1` **Tags input: move under name, remove hint/title** — Move the tags chip input directly below the name field in all entity editor modals; remove the hint toggle and section title for a cleaner layout
 ## WebUI Review (2026-03-16)
 ### Critical (Safety & Correctness)
 - [x] `P1` **"Stop All" buttons need confirmation** — dashboard, LED targets, KC targets
 - [x] `P1` **`turnOffDevice()` needs confirmation**
 - [x] `P1` **Confirm dialog i18n** — added data-i18n to title/buttons
 - [x] `P1` **Duplicate `id="tutorial-overlay"`** — renamed to calibration-tutorial-overlay
 - [x] `P1` **Define missing CSS variables** — --radius, --text-primary, --hover-bg, --input-bg
 - [x] `P1` **Toast z-index conflict** — toast now 3000
 ### UX Consistency
 - [x] `P1` **Test modals backdrop-close** — added setupBackdropClose
 - [x] `P1` **Devices clone** — added cloneDevice with full field prefill
 - [x] `P1` **Sync clocks in command palette** — added to _responseKeys + _buildItems
 - [x] `P2` **Hardcoded accent colors** — 20+ replacements using color-mix() and CSS vars
 - [x] `P2` **Duplicate `.badge` definition** — removed dead code from components.css
 - [x] `P2` **Calibration elements keyboard-accessible** — changed div to button
 - [x] `P2` **Color-picker swatch aria-labels** — added aria-label with hex value
 - [x] `P2` **Pattern canvas mobile scroll** — added min-width: 0 override in mobile.css
 - [x] `P2` **Graph editor mobile bottom clipping** — adjusted height in mobile.css
 ### Low Priority Polish
 - [x] `P3` **Empty-state illustrations/onboarding** — CardSection emptyKey with per-entity messages
 - [x] `P3` **api-key-modal submit title i18n**
 - [x] `P3` **Settings modal close labeled "Cancel" → "Close"**
 - [x] `P3` **Inconsistent px vs rem font sizes** — 21 conversions across streams/modal/cards CSS
 - [x] `P3` **scroll-behavior: smooth** — added with reduced-motion override
 - [x] `P3` **Reduce !important usage** — scoped .cs-filter selectors
 - [x] `P3` **@media print styles** — theme reset + hide nav
 - [x] `P3` **:focus-visible on interactive elements** — added 4 missing selectors
 - [x] `P3` **iOS Safari modal scroll-position jump** — already implemented in ui.js lockBody/unlockBody
 ### New Features
 - [x] `P1` **Command palette actions** — start/stop targets, activate scenes, enable/disable automations
 - [x] `P1` **Bulk start/stop API** — POST /output-targets/bulk/start and /bulk/stop
 - [x] `P1` **OS notification history viewer** — modal with app name, timestamp, fired/filtered badges
 - [x] `P1` **Scene "used by" reference count** — badge on card with automation count
 - [x] `P1` **Clock elapsed time on cards** — shows formatted elapsed time
 - [x] `P1` **Device "last seen" timestamp** — relative time with full ISO in title
 - [x] `P2` **Audio device refresh in modal** — refresh button next to device dropdown
 - [x] `P2` **Composite layer reorder** — drag handles with pointer-based reorder
 - [x] `P2` **MQTT settings panel** — config form with enabled/host/port/auth/topic, JSON persistence
 - [x] `P2` **Log viewer** — WebSocket broadcaster with ring buffer, level-filtered UI in settings
 - [x] `P2` **Animated value source waveform preview** — canvas drawing of sine/triangle/sawtooth/square
 - [x] `P2` **Gradient custom preset save** — localStorage-backed custom presets with save/delete
 - [x] `P2` **API key management UI** — read-only display of key labels with masked values
 - [x] `P2` **Backup metadata** — file size, auto/manual badge
 - [x] `P2` **Server restart button** — in settings with confirm dialog + restart overlay
 - [x] `P2` **Partial config export/import** — per-store export/import with merge option
 - [x] `P3` **Audio spectrum visualizer** — already fully implemented
 - [ ] `P3` **Hue bridge pairing flow** — requires physical Hue bridge hardware
 - [x] `P3` **Runtime log-level adjustment** — GET/PUT endpoints + settings dropdown
 - [x] `P3` **Progressive disclosure in target editor** — advanced section collapsed by default
 ### CSS Architecture
 - [x] `P1` **Define missing CSS variables** — --radius, --text-primary, --hover-bg, --input-bg
 - [x] `P2` **Define radius scale** — --radius-sm/md/lg/pill tokens, migrated key selectors
 - [x] `P2` **Scope generic input selector** — .cs-filter boosted specificity, 7 !important removed
 - [x] `P2` **Consolidate duplicate toggle switch** — filter-list uses settings-toggle
 - [x] `P2` **Replace hardcoded accent colors** — 20+ values → CSS vars with color-mix()
--- 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
@@ -0,0 +1,255 @@
 <#
 .SYNOPSIS
    Build a portable Windows distribution of LedGrab.
 .DESCRIPTION
    Downloads embedded Python, installs all dependencies, copies app code,
    builds the frontend bundle, and produces a self-contained ZIP.
 .PARAMETER Version
    Version string (e.g. "0.1.0" or "v0.1.0"). Auto-detected from git tag
    or __init__.py if omitted.
 .PARAMETER PythonVersion
    Embedded Python version to download. Default: 3.11.9
 .PARAMETER SkipFrontend
    Skip npm ci + npm run build (use if frontend is already built).
 .PARAMETER SkipPerf
    Skip installing optional [perf] extras (dxcam, bettercam, windows-capture).
 .EXAMPLE
    .\build-dist.ps1
    .\build-dist.ps1 -Version "0.2.0"
    .\build-dist.ps1 -SkipFrontend -SkipPerf
 #>
 param(
    [string]$Version = "",
    [string]$PythonVersion = "3.11.9",
    [switch]$SkipFrontend,
    [switch]$SkipPerf
 )
 $ErrorActionPreference = 'Stop'
 $ProgressPreference = 'SilentlyContinue'  # faster downloads
 $ScriptRoot = $PSScriptRoot
 $BuildDir = Join-Path $ScriptRoot "build"
 $DistName = "LedGrab"
 $DistDir = Join-Path $BuildDir $DistName
 $ServerDir = Join-Path $ScriptRoot "server"
 $PythonDir = Join-Path $DistDir "python"
 $AppDir = Join-Path $DistDir "app"
 # ── Version detection ──────────────────────────────────────────
 if (-not $Version) {
    # Try git tag
    try {
        $gitTag = git describe --tags --exact-match 2>$null
        if ($gitTag) { $Version = $gitTag }
    } catch {}
 }
 if (-not $Version) {
    # Try env var (CI)
    if ($env:GITEA_REF_NAME) { $Version = $env:GITEA_REF_NAME }
    elseif ($env:GITHUB_REF_NAME) { $Version = $env:GITHUB_REF_NAME }
 }
 if (-not $Version) {
    # Parse from __init__.py
    $initFile = Join-Path $ServerDir "src\wled_controller\__init__.py"
    $match = Select-String -Path $initFile -Pattern '__version__\s*=\s*"([^"]+)"'
    if ($match) { $Version = $match.Matches[0].Groups[1].Value }
 }
 if (-not $Version) { $Version = "0.0.0" }
 # Strip leading 'v' for filenames
 $VersionClean = $Version -replace '^v', ''
 $ZipName = "LedGrab-v${VersionClean}-win-x64.zip"
 Write-Host "=== Building LedGrab v${VersionClean} ===" -ForegroundColor Cyan
 Write-Host "  Python: $PythonVersion"
 Write-Host "  Output: build\$ZipName"
 Write-Host ""
 # ── Clean ──────────────────────────────────────────────────────
 if (Test-Path $DistDir) {
    Write-Host "[1/8] Cleaning previous build..."
    Remove-Item -Recurse -Force $DistDir
 }
 New-Item -ItemType Directory -Path $DistDir -Force | Out-Null
 # ── Download embedded Python ───────────────────────────────────
 $PythonZipUrl = "https://www.python.org/ftp/python/${PythonVersion}/python-${PythonVersion}-embed-amd64.zip"
 $PythonZipPath = Join-Path $BuildDir "python-embed.zip"
 Write-Host "[2/8] Downloading embedded Python ${PythonVersion}..."
 if (-not (Test-Path $PythonZipPath)) {
    Invoke-WebRequest -Uri $PythonZipUrl -OutFile $PythonZipPath
 }
 Write-Host "  Extracting to python/..."
 Expand-Archive -Path $PythonZipPath -DestinationPath $PythonDir -Force
 # ── Patch ._pth to enable site-packages ────────────────────────
 Write-Host "[3/8] Patching Python path configuration..."
 $pthFile = Get-ChildItem -Path $PythonDir -Filter "python*._pth" | Select-Object -First 1
 if (-not $pthFile) { throw "Could not find python*._pth in $PythonDir" }
 $pthContent = Get-Content $pthFile.FullName -Raw
 # Uncomment 'import site'
 $pthContent = $pthContent -replace '#\s*import site', 'import site'
 # Add Lib\site-packages if not present
 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)"
 # ── Install pip ────────────────────────────────────────────────
 Write-Host "[4/8] Installing pip..."
 $GetPipPath = Join-Path $BuildDir "get-pip.py"
 if (-not (Test-Path $GetPipPath)) {
    Invoke-WebRequest -Uri "https://bootstrap.pypa.io/get-pip.py" -OutFile $GetPipPath
 }
 $python = Join-Path $PythonDir "python.exe"
 $ErrorActionPreference = 'Continue'
 & $python $GetPipPath --no-warn-script-location 2>&1 | Out-Null
 $ErrorActionPreference = 'Stop'
 if ($LASTEXITCODE -ne 0) { throw "Failed to install pip" }
 # ── Install dependencies ──────────────────────────────────────
 Write-Host "[5/8] Installing dependencies..."
 $extras = "camera,notifications"
 if (-not $SkipPerf) { $extras += ",perf" }
 # Install the project (pulls all deps via pyproject.toml), then remove
 # the installed package itself — PYTHONPATH handles app code loading.
 $ErrorActionPreference = 'Continue'
 & $python -m pip install --no-warn-script-location "${ServerDir}[${extras}]" 2>&1 | ForEach-Object {
    if ($_ -match 'ERROR|Failed') { Write-Host "  $_" -ForegroundColor Red }
 }
 $ErrorActionPreference = 'Stop'
 if ($LASTEXITCODE -ne 0) {
    Write-Host "  Some optional deps may have failed (continuing)..." -ForegroundColor Yellow
 }
 # Remove the installed wled_controller package to avoid duplication
 $sitePackages = Join-Path $PythonDir "Lib\site-packages"
 Get-ChildItem -Path $sitePackages -Filter "wled*" -Directory | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 Get-ChildItem -Path $sitePackages -Filter "wled*.dist-info" -Directory | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 # Clean up caches and test files to reduce size
 Write-Host "  Cleaning up caches..."
 Get-ChildItem -Path $sitePackages -Recurse -Directory -Filter "__pycache__" | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 Get-ChildItem -Path $sitePackages -Recurse -Directory -Filter "tests" | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 Get-ChildItem -Path $sitePackages -Recurse -Directory -Filter "test" | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 # ── Build frontend ─────────────────────────────────────────────
 if (-not $SkipFrontend) {
    Write-Host "[6/8] Building frontend bundle..."
    Push-Location $ServerDir
    try {
        $ErrorActionPreference = 'Continue'
        & npm ci --loglevel error 2>&1 | Out-Null
        & npm run build 2>&1 | ForEach-Object {
            $line = "$_"
            if ($line -and $line -notmatch 'RemoteException') { Write-Host "  $line" }
        }
        $ErrorActionPreference = 'Stop'
    } finally {
        Pop-Location
    }
 } else {
    Write-Host "[6/8] Skipping frontend build (--SkipFrontend)"
 }
 # ── Copy application files ─────────────────────────────────────
 Write-Host "[7/8] Copying application files..."
 New-Item -ItemType Directory -Path $AppDir -Force | Out-Null
 # Copy source code (includes static/dist bundle, templates, locales)
 $srcDest = Join-Path $AppDir "src"
 Copy-Item -Path (Join-Path $ServerDir "src") -Destination $srcDest -Recurse
 # Copy config
 $configDest = Join-Path $AppDir "config"
 Copy-Item -Path (Join-Path $ServerDir "config") -Destination $configDest -Recurse
 # Create empty data/ and logs/ directories
 New-Item -ItemType Directory -Path (Join-Path $DistDir "data") -Force | Out-Null
 New-Item -ItemType Directory -Path (Join-Path $DistDir "logs") -Force | Out-Null
 # Clean up source maps and __pycache__ from app code
 Get-ChildItem -Path $srcDest -Recurse -Filter "*.map" | Remove-Item -Force -ErrorAction SilentlyContinue
 Get-ChildItem -Path $srcDest -Recurse -Directory -Filter "__pycache__" | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 # ── Create launcher ────────────────────────────────────────────
 Write-Host "[8/8] Creating launcher..."
 $launcherContent = @'
@echo off
 title LedGrab v%VERSION%
 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"
 echo.
 echo  =============================================
 echo   LedGrab v%VERSION%
 echo   Open http://localhost:8080 in your browser
 echo  =============================================
 echo.
 :: Start the server (open browser after short delay)
 start "" /b cmd /c "timeout /t 2 /nobreak >nul && start http://localhost:8080"
 "%~dp0python\python.exe" -m uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
 pause
 '@
 $launcherContent = $launcherContent -replace '%VERSION%', $VersionClean
 $launcherPath = Join-Path $DistDir "LedGrab.bat"
 Set-Content -Path $launcherPath -Value $launcherContent -Encoding ASCII
 # ── Create ZIP ─────────────────────────────────────────────────
 $ZipPath = Join-Path $BuildDir $ZipName
 if (Test-Path $ZipPath) { Remove-Item -Force $ZipPath }
 Write-Host ""
 Write-Host "Creating $ZipName..." -ForegroundColor Cyan
 # Use 7-Zip if available (faster, handles locked files), else fall back to Compress-Archive
 $7z = Get-Command 7z -ErrorAction SilentlyContinue
 if ($7z) {
    & 7z a -tzip -mx=7 $ZipPath "$DistDir\*" | Select-Object -Last 3
 } else {
    Compress-Archive -Path "$DistDir\*" -DestinationPath $ZipPath -CompressionLevel Optimal
 }
 $zipSize = (Get-Item $ZipPath).Length / 1MB
 Write-Host ""
 Write-Host "=== Build complete ===" -ForegroundColor Green
 Write-Host "  Archive: $ZipPath"
 Write-Host "  Size: $([math]::Round($zipSize, 1)) MB"
 Write-Host ""
--- 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/contexts/ci-cd.md
+++ b/contexts/ci-cd.md
@@ -0,0 +1,80 @@
 # CI/CD & Release Workflow
 ## Workflows
 | File | Trigger | Purpose |
 |------|---------|---------|
 | `.gitea/workflows/test.yml` | Push/PR to master | Lint (ruff) + pytest |
 | `.gitea/workflows/release.yml` | Tag `v*` | Build artifacts + create Gitea release |
 ## Release Pipeline (`release.yml`)
 Four parallel jobs triggered by pushing a `v*` tag:
 ### 1. `create-release`
 Creates the Gitea release with a description table listing all artifacts. **The description must stay in sync with actual build outputs** — if you add/remove/rename an artifact, update the body template here.
 ### 2. `build-windows` (cross-built from Linux)
 - Runs `build-dist-windows.sh` on Ubuntu with NSIS + msitools
 - Downloads Windows embedded Python 3.11 + pip wheels cross-platform
 - Bundles tkinter from Python MSI via msiextract
 - Builds frontend (`npm run build`)
 - Pre-compiles Python bytecode (`compileall`)
 - Produces: **`LedGrab-{tag}-win-x64.zip`** (portable) and **`LedGrab-{tag}-setup.exe`** (NSIS installer)
 ### 3. `build-linux`
 - Runs `build-dist.sh` on Ubuntu
 - Creates a venv, installs deps, builds frontend
 - Produces: **`LedGrab-{tag}-linux-x64.tar.gz`**
 ### 4. `build-docker`
 - Plain `docker build` + `docker push` (no Buildx — TrueNAS runners lack nested networking)
 - Registry: `{gitea_host}/{repo}:{tag}`
 - Tags: `v0.x.x`, `0.x.x`, and `latest` (stable only, not alpha/beta/rc)
 ## Build Scripts
 | Script | Platform | Output |
 |--------|----------|--------|
 | `build-dist-windows.sh` | Linux → Windows cross-build | ZIP + NSIS installer |
 | `build-dist.sh` | Linux native | tarball |
 | `server/Dockerfile` | Docker | Container image |
 ## Release Versioning
 - Tags: `v{major}.{minor}.{patch}` for stable, `v{major}.{minor}.{patch}-alpha.{n}` for pre-release
 - Pre-release tags set `prerelease: true` on the Gitea release
 - Docker `latest` tag only applied to stable releases
 - Version in `server/pyproject.toml` should match the tag (without `v` prefix)
 ## CI Runners
 - Two TrueNAS Gitea runners with `ubuntu` tags
 - No Windows runner available — Windows builds are cross-compiled from Linux
 - Docker Buildx not available (networking limitations) — use plain `docker build`
 ## Test Pipeline (`test.yml`)
 - Installs `opencv-python-headless` and `libportaudio2` for CI compatibility
 - Display-dependent tests are skipped via `@requires_display` marker
 - Uses `python` not `python3` (Git Bash on Windows resolves `python3` to MS Store stub)
 ## Common Tasks
 ### Creating a release
 ```bash
 git tag v0.2.0
 git push origin v0.2.0
 ```
 ### Creating a pre-release
 ```bash
 git tag v0.2.0-alpha.1
 git push origin v0.2.0-alpha.1
 ```
 ### Adding a new build artifact
 1. Update the build script to produce the new file
 2. Add upload step in the relevant `build-*` job
 3. **Update the release description** in `create-release` job body template
 4. Test with a pre-release tag first
--- a/contexts/frontend.md
+++ b/contexts/frontend.md
@@ -72,17 +72,17 @@ For `EntitySelect` with `allowNone: true`, pass the same i18n string as `noneLab
 Plain `<select>` dropdowns should be enhanced with visual selectors depending on the data type:
- **Predefined options** (source types, effect types, palettes, waveforms, viz modes) → use `IconSelect` from `js/core/icon-select.js`. This replaces the `<select>` with a visual grid of icon+label+description cells. See `_ensureCSSTypeIconSelect()`, `_ensureEffectTypeIconSelect()`, `_ensureInterpolationIconSelect()` in `color-strips.js` for examples.
+- **Predefined options** (source types, effect types, palettes, waveforms, viz modes) → use `IconSelect` from `js/core/icon-select.ts`. This replaces the `<select>` with a visual grid of icon+label+description cells. See `_ensureCSSTypeIconSelect()`, `_ensureEffectTypeIconSelect()`, `_ensureInterpolationIconSelect()` in `color-strips.ts` for examples.
- **Entity references** (picture sources, audio sources, devices, templates, clocks) → use `EntitySelect` from `js/core/entity-palette.js`. This replaces the `<select>` with a searchable command-palette-style picker. See `_cssPictureSourceEntitySelect` in `color-strips.js` or `_lineSourceEntitySelect` in `advanced-calibration.js` for examples.
+- **Entity references** (picture sources, audio sources, devices, templates, clocks) → use `EntitySelect` from `js/core/entity-palette.ts`. This replaces the `<select>` with a searchable command-palette-style picker. See `_cssPictureSourceEntitySelect` in `color-strips.ts` or `_lineSourceEntitySelect` in `advanced-calibration.ts` for examples.
 Both widgets hide the native `<select>` but keep it in the DOM with its value in sync. After programmatically changing the `<select>` value, call `.refresh()` (EntitySelect) or `.setValue(val)` (IconSelect) to update the trigger display. Call `.destroy()` when the modal closes.
-**IMPORTANT:** For `IconSelect` item icons, use SVG icons from `js/core/icon-paths.js` (via `_icon(P.iconName)`) or styled `<span>` elements (e.g., `<span style="font-weight:bold">A</span>`). **Never use emoji** — they render inconsistently across platforms and themes.
+**IMPORTANT:** For `IconSelect` item icons, use SVG icons from `js/core/icon-paths.ts` (via `_icon(P.iconName)`) or styled `<span>` elements (e.g., `<span style="font-weight:bold">A</span>`). **Never use emoji** — they render inconsistently across platforms and themes.
 ### Modal dirty check (discard unsaved changes)
-Every editor modal **must** have a dirty check so closing with unsaved changes shows a "Discard unsaved changes?" confirmation. Use the `Modal` base class pattern from `js/core/modal.js`:
+Every editor modal **must** have a dirty check so closing with unsaved changes shows a "Discard unsaved changes?" confirmation. Use the `Modal` base class pattern from `js/core/modal.ts`:
 1. **Subclass Modal** with `snapshotValues()` returning an object of all tracked field values:
@@ -144,25 +144,25 @@ Do **not** use a `range-with-value` wrapper div.
 ### Tutorials
-The app has an interactive tutorial system (`static/js/features/tutorials.js`) with a generic engine, spotlight overlay, tooltip positioning, and keyboard navigation. Tutorials exist for:
+The app has an interactive tutorial system (`static/js/features/tutorials.ts`) with a generic engine, spotlight overlay, tooltip positioning, and keyboard navigation. Tutorials exist for:
 - **Getting started** (header-level walkthrough of all tabs and controls)
 - **Per-tab tutorials** (Dashboard, Targets, Sources, Profiles) triggered by `?` buttons
 - **Device card tutorial** and **Calibration tutorial** (context-specific)
-When adding **new tabs, sections, or major UI elements**, update the corresponding tutorial step array in `tutorials.js` and add `tour.*` i18n keys to all 3 locale files (`en.json`, `ru.json`, `zh.json`).
+When adding **new tabs, sections, or major UI elements**, update the corresponding tutorial step array in `tutorials.ts` and add `tour.*` i18n keys to all 3 locale files (`en.json`, `ru.json`, `zh.json`).
 ## Icons
 **Always use SVG icons from the icon system, never text/emoji/Unicode symbols for buttons and UI controls.**
- Icon SVG paths are defined in `static/js/core/icon-paths.js` (Lucide icons, 24×24 viewBox)
+- Icon SVG paths are defined in `static/js/core/icon-paths.ts` (Lucide icons, 24×24 viewBox)
- Icon constants are exported from `static/js/core/icons.js` (e.g. `ICON_START`, `ICON_TRASH`, `ICON_EDIT`)
+- Icon constants are exported from `static/js/core/icons.ts` (e.g. `ICON_START`, `ICON_TRASH`, `ICON_EDIT`)
- Use `_svg(path)` wrapper from `icons.js` to create new icon constants from paths
+- Use `_svg(path)` wrapper from `icons.ts` to create new icon constants from paths
 When you need a new icon:
 1. Find the Lucide icon at https://lucide.dev
 2. Copy the inner SVG elements (paths, circles, rects) into `icon-paths.js` as a new export
-3. Add a corresponding `ICON_*` constant in `icons.js` using `_svg(P.myIcon)`
+3. Add a corresponding `ICON_*` constant in `icons.ts` using `_svg(P.myIcon)`
 4. Import and use the constant in your feature module
 Common icons: `ICON_START` (play), `ICON_STOP` (power), `ICON_EDIT` (pencil), `ICON_CLONE` (copy), `ICON_TRASH` (trash), `ICON_SETTINGS` (gear), `ICON_TEST` (flask), `ICON_OK` (circle-check), `ICON_WARNING` (triangle-alert), `ICON_HELP` (circle-help), `ICON_LIST_CHECKS` (list-checks), `ICON_CIRCLE_OFF` (circle-off).
@@ -171,9 +171,9 @@ For icon-only buttons, use `btn btn-icon` CSS classes. The `.icon` class inside
 ## Localization (i18n)
-**Every user-facing string must be localized.** Never use hardcoded English strings in `showToast()`, `error.textContent`, modal messages, or any other UI-visible text. Always use `t('key')` from `../core/i18n.js` and add the corresponding key to **all three** locale files (`en.json`, `ru.json`, `zh.json`).
+**Every user-facing string must be localized.** Never use hardcoded English strings in `showToast()`, `error.textContent`, modal messages, or any other UI-visible text. Always use `t('key')` from `../core/i18n.ts` and add the corresponding key to **all three** locale files (`en.json`, `ru.json`, `zh.json`).
- In JS modules: `import { t } from '../core/i18n.js';` then `showToast(t('my.key'), 'error')`
+- In JS modules: `import { t } from '../core/i18n.ts';` then `showToast(t('my.key'), 'error')`
 - In inline `<script>` blocks (where `t()` may not be available yet): use `window.t ? t('key') : 'fallback'`
 - In HTML templates: use `data-i18n="key"` for text content, `data-i18n-title="key"` for title attributes, `data-i18n-aria-label="key"` for aria-labels
 - Keys follow dotted namespace convention: `feature.context.description` (e.g. `device.error.brightness`, `calibration.saved`)
@@ -196,7 +196,7 @@ The frontend uses **esbuild** to bundle all JS modules and CSS files into single
 ### Files
- **Entry points:** `static/js/app.js` (JS), `static/css/all.css` (CSS imports all individual sheets)
+- **Entry points:** `static/js/app.ts` (JS), `static/css/all.css` (CSS imports all individual sheets)
 - **Output:** `static/dist/app.bundle.js` and `static/dist/app.bundle.css` (minified + source maps)
 - **Config:** `server/esbuild.mjs`
 - **HTML:** `templates/index.html` references the bundles, not individual source files
@@ -219,8 +219,8 @@ The frontend uses **esbuild** to bundle all JS modules and CSS files into single
 All JS/CSS dependencies are bundled — **no CDN or external requests** at runtime:
- **Chart.js** — imported in `perf-charts.js`, exposed as `window.Chart` for `targets.js` and `dashboard.js`
+- **Chart.js** — imported in `perf-charts.ts`, exposed as `window.Chart` for `targets.ts` and `dashboard.ts`
- **ELK.js** — imported in `graph-layout.js` for graph auto-layout
+- **ELK.js** — imported in `graph-layout.ts` for graph auto-layout
 - **Fonts** — DM Sans (400-700) and Orbitron (700) woff2 files in `static/fonts/`, declared in `css/fonts.css`
 When adding a new JS dependency: `npm install <pkg>` in `server/`, then `import` it in the relevant source file. esbuild bundles it automatically.
@@ -260,7 +260,7 @@ Reference: `.dashboard-metric-value` in `dashboard.css` uses `font-family: var(-
 ### FPS sparkline charts
-Use `createFpsSparkline(canvasId, actualHistory, currentHistory, fpsTarget)` from `core/chart-utils.js`. Wrap the canvas in `.target-fps-sparkline` (36px height, `position: relative`, `overflow: hidden`). Show the value in `.target-fps-label` with `.metric-value` and `.target-fps-avg`.
+Use `createFpsSparkline(canvasId, actualHistory, currentHistory, fpsTarget)` from `core/chart-utils.ts`. Wrap the canvas in `.target-fps-sparkline` (36px height, `position: relative`, `overflow: hidden`). Show the value in `.target-fps-label` with `.metric-value` and `.target-fps-avg`.
 ## Visual Graph Editor
--- a/contexts/graph-editor.md
+++ b/contexts/graph-editor.md
@@ -1,6 +1,6 @@
 # Visual Graph Editor
-**Read this file when working on the graph editor** (`static/js/features/graph-editor.js` and related modules).
+**Read this file when working on the graph editor** (`static/js/features/graph-editor.ts` and related modules).
 ## Architecture
@@ -10,12 +10,12 @@ The graph editor renders all entities (devices, templates, sources, clocks, targ
 | File | Responsibility |
 |---|---|
-| `js/features/graph-editor.js` | Main orchestrator — toolbar, keyboard, search, filter, add-entity menu, port/node drag, minimap |
+| `js/features/graph-editor.ts` | Main orchestrator — toolbar, keyboard, search, filter, add-entity menu, port/node drag, minimap |
-| `js/core/graph-layout.js` | ELK.js layout, `buildGraph()`, `computePorts()`, entity color/label maps |
+| `js/core/graph-layout.ts` | ELK.js layout, `buildGraph()`, `computePorts()`, entity color/label maps |
-| `js/core/graph-nodes.js` | SVG node rendering, overlay buttons, per-node color overrides |
+| `js/core/graph-nodes.ts` | SVG node rendering, overlay buttons, per-node color overrides |
-| `js/core/graph-edges.js` | SVG edge rendering (bezier curves, arrowheads, flow dots) |
+| `js/core/graph-edges.ts` | SVG edge rendering (bezier curves, arrowheads, flow dots) |
-| `js/core/graph-canvas.js` | Pan/zoom controller with `zoomToPoint()` rAF animation |
+| `js/core/graph-canvas.ts` | Pan/zoom controller with `zoomToPoint()` rAF animation |
-| `js/core/graph-connections.js` | CONNECTION_MAP — which fields link entity types, drag-connect/detach logic |
+| `js/core/graph-connections.ts` | CONNECTION_MAP — which fields link entity types, drag-connect/detach logic |
 | `css/graph-editor.css` | All graph-specific styles |
 ### Data flow
@@ -41,27 +41,27 @@ Nodes have input ports (left) and output ports (right), colored by edge type. Po
 ### Adding a new entity type
-1. **`graph-layout.js`** — `ENTITY_COLORS`, `ENTITY_LABELS`, `buildGraph()` (add node loop + edge loops)
+1. **`graph-layout.ts`** — `ENTITY_COLORS`, `ENTITY_LABELS`, `buildGraph()` (add node loop + edge loops)
-2. **`graph-layout.js`** — `edgeType()` function if the new type needs a distinct edge color
+2. **`graph-layout.ts`** — `edgeType()` function if the new type needs a distinct edge color
-3. **`graph-nodes.js`** — `KIND_ICONS` (default icon), `SUBTYPE_ICONS` (subtype-specific icons)
+3. **`graph-nodes.ts`** — `KIND_ICONS` (default icon), `SUBTYPE_ICONS` (subtype-specific icons)
-4. **`graph-nodes.js`** — `START_STOP_KINDS` or `TEST_KINDS` sets if the entity supports start/stop or test
+4. **`graph-nodes.ts`** — `START_STOP_KINDS` or `TEST_KINDS` sets if the entity supports start/stop or test
-5. **`graph-connections.js`** — `CONNECTION_MAP` for drag-connect edge creation
+5. **`graph-connections.ts`** — `CONNECTION_MAP` for drag-connect edge creation
-6. **`graph-editor.js`** — `ADD_ENTITY_MAP` (add-entity menu entry with window function)
+6. **`graph-editor.ts`** — `ADD_ENTITY_MAP` (add-entity menu entry with window function)
-7. **`graph-editor.js`** — `ALL_CACHES` array (for new-entity-focus watcher)
+7. **`graph-editor.ts`** — `ALL_CACHES` array (for new-entity-focus watcher)
-8. **`graph-editor.js`** — `_fetchAllEntities()` (add cache fetch + pass to `computeLayout`)
+8. **`graph-editor.ts`** — `_fetchAllEntities()` (add cache fetch + pass to `computeLayout`)
-9. **`core/state.js`** — Add/export the new DataCache
+9. **`core/state.ts`** — Add/export the new DataCache
-10. **`app.js`** — Import and window-export the add/edit/clone functions
+10. **`app.ts`** — Import and window-export the add/edit/clone functions
 ### Adding a new field/connection to an existing entity
-1. **`graph-layout.js`** — `buildGraph()` edges section: add `addEdge()` call
+1. **`graph-layout.ts`** — `buildGraph()` edges section: add `addEdge()` call
-2. **`graph-connections.js`** — `CONNECTION_MAP`: add the field entry
+2. **`graph-connections.ts`** — `CONNECTION_MAP`: add the field entry
-3. **`graph-edges.js`** — `EDGE_COLORS` if a new edge type is needed
+3. **`graph-edges.ts`** — `EDGE_COLORS` if a new edge type is needed
 ### Adding a new entity subtype
-1. **`graph-nodes.js`** — `SUBTYPE_ICONS[kind]` — add icon for the new subtype
+1. **`graph-nodes.ts`** — `SUBTYPE_ICONS[kind]` — add icon for the new subtype
-2. **`graph-layout.js`** — `buildGraph()` — ensure `subtype` is extracted from the entity data
+2. **`graph-layout.ts`** — `buildGraph()` — ensure `subtype` is extracted from the entity data
 ## Features & keyboard shortcuts
@@ -90,7 +90,7 @@ Rendered as a small SVG with colored rects for each node and a viewport rect. Su
 ## Node hover FPS tooltip
-Running `output_target` nodes show a floating HTML tooltip on hover (300ms delay). The tooltip is an absolutely-positioned `<div class="graph-node-tooltip">` inside `.graph-container` (not SVG — needed for Chart.js canvas). It displays errors, uptime, and a FPS sparkline (reusing `createFpsSparkline` from `core/chart-utils.js`). The sparkline is seeded from `/api/v1/system/metrics-history` for instant context.
+Running `output_target` nodes show a floating HTML tooltip on hover (300ms delay). The tooltip is an absolutely-positioned `<div class="graph-node-tooltip">` inside `.graph-container` (not SVG — needed for Chart.js canvas). It displays errors, uptime, and a FPS sparkline (reusing `createFpsSparkline` from `core/chart-utils.ts`). The sparkline is seeded from `/api/v1/system/metrics-history` for instant context.
 **Hover events** use `pointerover`/`pointerout` with `relatedTarget` check to prevent flicker when the cursor moves between child SVG elements within the same `<g>` node.
--- a/contexts/server-operations.md
+++ b/contexts/server-operations.md
@@ -0,0 +1,78 @@
 # Server Operations
 **Read this file when restarting, starting, or managing the server process.**
 ## Server Modes
 Two independent server modes with separate configs, ports, and data directories:
 | Mode | Command | Config | Port | API Key | Data |
 | ---- | ------- | ------ | ---- | ------- | ---- |
 | **Real** | `python -m wled_controller.main` | `config/default_config.yaml` | 8080 | `development-key-change-in-production` | `data/` |
 | **Demo** | `python -m wled_controller.demo` | `config/demo_config.yaml` | 8081 | `demo` | `data/demo/` |
 Both can run simultaneously on different ports.
 ## Restart Procedure
 ### Real server
 Use the PowerShell restart script — it reliably stops only the server process and starts a new detached instance:
 ```bash
 powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\wled-screen-controller\server\restart.ps1"
 ```
 ### Demo server
 Find and kill the process on port 8081, then restart:
 ```bash
 # Find PID
 powershell -Command "netstat -ano | Select-String ':8081.*LISTEN'"
 # Kill it
 powershell -Command "Stop-Process -Id <PID> -Force"
 # Restart
 cd server && python -m wled_controller.demo
 ```
 **Do NOT use** `Stop-Process -Name python` — it kills unrelated Python processes (VS Code extensions, etc.).
 **Do NOT use** bash background `&` jobs — they get killed when the shell session ends.
 ## When to Restart
 **Restart required** for changes to:
 - API routes (`api/routes/`, `api/schemas/`)
 - Core logic (`core/*.py`)
 - Configuration (`config.py`)
 - Utilities (`utils/*.py`)
 - Data models (`storage/`)
 **No restart needed** for:
 - Static files (`static/js/`, `static/css/`) — but **must rebuild bundle**: `cd server && npm run build`
 - Locale files (`static/locales/*.json`) — loaded by frontend
 - Documentation files (`*.md`)
 ## Auto-Reload Note
 Auto-reload is disabled (`reload=False` in `main.py`) due to watchfiles causing an infinite reload loop. Manual restart is required after server code changes.
 ## Demo Mode Awareness
 **When adding new entity types, engines, device providers, or stores — keep demo mode in sync:**
 1. **New entity stores**: Add the store's file path to `StorageConfig` in `config.py` — `model_post_init()` auto-rewrites `data/` to `data/demo/` paths when demo is active.
 2. **New capture engines**: Verify demo mode filtering works — demo engines use `is_demo_mode()` gate in `is_available()`.
 3. **New audio engines**: Same as capture engines — `is_available()` must respect `is_demo_mode()`.
 4. **New device providers**: Gate discovery with `is_demo_mode()` like `DemoDeviceProvider.discover()`.
 5. **New seed data**: Update `server/src/wled_controller/core/demo_seed.py` to include sample entities.
 6. **Frontend indicators**: Demo state exposed via `GET /api/v1/version` -> `demo_mode: bool`. Frontend stores it as `demoMode` in app state and sets `document.body.dataset.demo = 'true'`.
 7. **Backup/Restore**: New stores added to `STORE_MAP` in `system.py` automatically work in demo mode since the data directory is already isolated.
 ### Key files
 - Config flag: `server/src/wled_controller/config.py` -> `Config.demo`, `is_demo_mode()`
 - Demo engines: `core/capture_engines/demo_engine.py`, `core/audio/demo_engine.py`
 - Demo devices: `core/devices/demo_provider.py`
 - Seed data: `core/demo_seed.py`
--- a/custom_components/wled_screen_controller/init.py
+++ b/custom_components/wled_screen_controller/init.py
@@ -114,15 +114,17 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    }
    # Track target and scene IDs to detect changes
-    initial_target_ids = set(
+    known_target_ids = set(
        coordinator.data.get("targets", {}).keys() if coordinator.data else []
    )
-    initial_scene_ids = set(
+    known_scene_ids = set(
        p["id"] for p in (coordinator.data.get("scene_presets", []) if coordinator.data else [])
    )
    def _on_coordinator_update() -> None:
        """Manage WS connections and detect target list changes."""
        nonlocal known_target_ids, known_scene_ids
        if not coordinator.data:
            return
@@ -134,8 +136,10 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
            state = target_data.get("state") or {}
            if info.get("target_type") == TARGET_TYPE_KEY_COLORS:
                if state.get("processing"):
                    if target_id not in ws_manager._connections:
                        hass.async_create_task(ws_manager.start_listening(target_id))
                else:
                    if target_id in ws_manager._connections:
                        hass.async_create_task(ws_manager.stop_listening(target_id))
        # Reload if target or scene list changed
@@ -143,7 +147,9 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
        current_scene_ids = set(
            p["id"] for p in coordinator.data.get("scene_presets", [])
        )
-        if current_ids != initial_target_ids or current_scene_ids != initial_scene_ids:
+        if current_ids != known_target_ids or current_scene_ids != known_scene_ids:
            known_target_ids = current_ids
            known_scene_ids = current_scene_ids
            _LOGGER.info("Target or scene list changed, reloading integration")
            hass.async_create_task(
                hass.config_entries.async_reload(entry.entry_id)
@@ -156,11 +162,18 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
        """Handle the set_leds service call."""
        source_id = call.data["source_id"]
        segments = call.data["segments"]
        # Route to the coordinator that owns this source
        for entry_data in hass.data[DOMAIN].values():
            coord = entry_data.get(DATA_COORDINATOR)
-            if coord:
+            if not coord or not coord.data:
                continue
            source_ids = {
                s["id"] for s in coord.data.get("css_sources", [])
            }
            if source_id in source_ids:
                await coord.push_segments(source_id, segments)
-                break
+                return
        _LOGGER.error("No server found with source_id %s", source_id)
    if not hass.services.has_service(DOMAIN, "set_leds"):
        hass.services.async_register(
@@ -188,5 +201,8 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    if unload_ok:
        hass.data[DOMAIN].pop(entry.entry_id)
        # Unregister service if no entries remain
        if not hass.data[DOMAIN]:
            hass.services.async_remove(DOMAIN, "set_leds")
    return unload_ok
--- a/custom_components/wled_screen_controller/button.py
+++ b/custom_components/wled_screen_controller/button.py
@@ -65,10 +65,9 @@ class SceneActivateButton(CoordinatorEntity, ButtonEntity):
        """Return if entity is available."""
        if not self.coordinator.data:
            return False
-        return any(
+        return self._preset_id in {
-            p["id"] == self._preset_id
+            p["id"] for p in self.coordinator.data.get("scene_presets", [])
-            for p in self.coordinator.data.get("scene_presets", [])
+        }
        )
    async def async_press(self) -> None:
        """Activate the scene preset."""
--- a/custom_components/wled_screen_controller/coordinator.py
+++ b/custom_components/wled_screen_controller/coordinator.py
@@ -37,7 +37,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        self.api_key = api_key
        self.server_version = "unknown"
        self._auth_headers = {"Authorization": f"Bearer {api_key}"}
-        self._pattern_cache: dict[str, list[dict]] = {}
+        self._timeout = aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT)
        super().__init__(
            hass,
@@ -85,7 +85,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
                        kc_settings = target.get("key_colors_settings") or {}
                        template_id = kc_settings.get("pattern_template_id", "")
                        if template_id:
-                            result["rectangles"] = await self._get_rectangles(
+                            result["rectangles"] = await self._fetch_rectangles(
                                template_id
                            )
                        else:
@@ -136,7 +136,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        try:
            async with self.session.get(
                f"{self.server_url}/health",
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
@@ -150,7 +150,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.get(
            f"{self.server_url}/api/v1/output-targets",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            resp.raise_for_status()
            data = await resp.json()
@@ -161,7 +161,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.get(
            f"{self.server_url}/api/v1/output-targets/{target_id}/state",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            resp.raise_for_status()
            return await resp.json()
@@ -171,27 +171,22 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.get(
            f"{self.server_url}/api/v1/output-targets/{target_id}/metrics",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            resp.raise_for_status()
            return await resp.json()
-    async def _get_rectangles(self, template_id: str) -> list[dict]:
+    async def _fetch_rectangles(self, template_id: str) -> list[dict]:
-        """Get rectangles for a pattern template, using cache."""
+        """Fetch rectangles for a pattern template (no cache — always fresh)."""
        if template_id in self._pattern_cache:
            return self._pattern_cache[template_id]
        try:
            async with self.session.get(
                f"{self.server_url}/api/v1/pattern-templates/{template_id}",
                headers=self._auth_headers,
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
-                rectangles = data.get("rectangles", [])
+                return data.get("rectangles", [])
                self._pattern_cache[template_id] = rectangles
                return rectangles
        except Exception as err:
            _LOGGER.warning(
                "Failed to fetch pattern template %s: %s", template_id, err
@@ -204,7 +199,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            async with self.session.get(
                f"{self.server_url}/api/v1/devices",
                headers=self._auth_headers,
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
@@ -213,18 +208,16 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            _LOGGER.warning("Failed to fetch devices: %s", err)
            return {}
-        devices_data: dict[str, dict[str, Any]] = {}
+        # Fetch brightness for all capable devices in parallel
-
+        async def fetch_device_entry(device: dict) -> tuple[str, dict[str, Any]]:
        for device in devices:
            device_id = device["id"]
            entry: dict[str, Any] = {"info": device, "brightness": None}
            if "brightness_control" in (device.get("capabilities") or []):
                try:
                    async with self.session.get(
                        f"{self.server_url}/api/v1/devices/{device_id}/brightness",
                        headers=self._auth_headers,
-                        timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                        timeout=self._timeout,
                    ) as resp:
                        if resp.status == 200:
                            bri_data = await resp.json()
@@ -234,7 +227,19 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
                        "Failed to fetch brightness for device %s: %s",
                        device_id, err,
                    )
            return device_id, entry
        results = await asyncio.gather(
            *(fetch_device_entry(d) for d in devices),
            return_exceptions=True,
        )
        devices_data: dict[str, dict[str, Any]] = {}
        for r in results:
            if isinstance(r, Exception):
                _LOGGER.warning("Device fetch failed: %s", r)
                continue
            device_id, entry = r
            devices_data[device_id] = entry
        return devices_data
@@ -245,7 +250,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/devices/{device_id}/brightness",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json={"brightness": brightness},
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -262,7 +267,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/devices/{device_id}/color",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json={"color": color},
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -280,7 +285,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/output-targets/{target_id}",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json={"key_colors_settings": {"brightness": brightness_float}},
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -297,7 +302,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            async with self.session.get(
                f"{self.server_url}/api/v1/color-strip-sources",
                headers=self._auth_headers,
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
@@ -312,7 +317,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            async with self.session.get(
                f"{self.server_url}/api/v1/value-sources",
                headers=self._auth_headers,
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
@@ -327,7 +332,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            async with self.session.get(
                f"{self.server_url}/api/v1/scene-presets",
                headers=self._auth_headers,
-                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+                timeout=self._timeout,
            ) as resp:
                resp.raise_for_status()
                data = await resp.json()
@@ -342,7 +347,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/color-strip-sources/{source_id}/colors",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json={"colors": colors},
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status not in (200, 204):
                body = await resp.text()
@@ -358,7 +363,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/color-strip-sources/{source_id}/colors",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json={"segments": segments},
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status not in (200, 204):
                body = await resp.text()
@@ -373,7 +378,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.post(
            f"{self.server_url}/api/v1/scene-presets/{preset_id}/activate",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -390,7 +395,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
            f"{self.server_url}/api/v1/color-strip-sources/{source_id}",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json=kwargs,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -398,14 +403,15 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
                    "Failed to update source %s: %s %s",
                    source_id, resp.status, body,
                )
                resp.raise_for_status()
    async def update_target(self, target_id: str, **kwargs: Any) -> None:
-        """Update a output target's fields."""
+        """Update an output target's fields."""
        async with self.session.put(
            f"{self.server_url}/api/v1/output-targets/{target_id}",
            headers={**self._auth_headers, "Content-Type": "application/json"},
            json=kwargs,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status != 200:
                body = await resp.text()
@@ -421,7 +427,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.post(
            f"{self.server_url}/api/v1/output-targets/{target_id}/start",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status == 409:
                _LOGGER.debug("Target %s already processing", target_id)
@@ -439,7 +445,7 @@ class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
        async with self.session.post(
            f"{self.server_url}/api/v1/output-targets/{target_id}/stop",
            headers=self._auth_headers,
-            timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT),
+            timeout=self._timeout,
        ) as resp:
            if resp.status == 409:
                _LOGGER.debug("Target %s already stopped", target_id)
--- a/custom_components/wled_screen_controller/light.py
+++ b/custom_components/wled_screen_controller/light.py
@@ -63,9 +63,13 @@ class ApiInputLight(CoordinatorEntity, LightEntity):
        self._entry_id = entry_id
        self._attr_unique_id = f"{self._source_id}_light"
-        # Local state — not derived from coordinator data
+        # Restore state from fallback_color
-        self._is_on: bool = False
+        fallback = self._get_fallback_color()
-        self._rgb_color: tuple[int, int, int] = (255, 255, 255)
+        is_off = fallback == [0, 0, 0]
        self._is_on: bool = not is_off
        self._rgb_color: tuple[int, int, int] = (
            (255, 255, 255) if is_off else tuple(fallback)  # type: ignore[arg-type]
        )
        self._brightness: int = 255
    @property
--- a/custom_components/wled_screen_controller/manifest.json
+++ b/custom_components/wled_screen_controller/manifest.json
@@ -4,9 +4,9 @@
  "codeowners": ["@alexeidolgolyov"],
  "config_flow": true,
  "dependencies": [],
-  "documentation": "https://github.com/yourusername/wled-screen-controller",
+  "documentation": "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed",
  "iot_class": "local_push",
-  "issue_tracker": "https://github.com/yourusername/wled-screen-controller/issues",
+  "issue_tracker": "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues",
  "requirements": ["aiohttp>=3.9.0"],
  "version": "0.2.0"
 }
--- a/custom_components/wled_screen_controller/select.py
+++ b/custom_components/wled_screen_controller/select.py
@@ -96,7 +96,7 @@ class CSSSourceSelect(CoordinatorEntity, SelectEntity):
        return self._target_id in self.coordinator.data.get("targets", {})
    async def async_select_option(self, option: str) -> None:
-        source_id = self._name_to_id(option)
+        source_id = self._name_to_id_map().get(option)
        if source_id is None:
            _LOGGER.error("CSS source not found: %s", option)
            return
@@ -104,12 +104,9 @@ class CSSSourceSelect(CoordinatorEntity, SelectEntity):
            self._target_id, color_strip_source_id=source_id
        )
-    def _name_to_id(self, name: str) -> str | None:
+    def _name_to_id_map(self) -> dict[str, str]:
        sources = (self.coordinator.data or {}).get("css_sources") or []
-        for s in sources:
+        return {s["name"]: s["id"] for s in sources}
            if s["name"] == name:
                return s["id"]
        return None
 class BrightnessSourceSelect(CoordinatorEntity, SelectEntity):
@@ -167,17 +164,14 @@ class BrightnessSourceSelect(CoordinatorEntity, SelectEntity):
        if option == NONE_OPTION:
            source_id = ""
        else:
-            source_id = self._name_to_id(option)
+            name_map = {
                s["name"]: s["id"]
                for s in (self.coordinator.data or {}).get("value_sources") or []
            }
            source_id = name_map.get(option)
            if source_id is None:
                _LOGGER.error("Value source not found: %s", option)
                return
        await self.coordinator.update_target(
            self._target_id, brightness_value_source_id=source_id
        )
    def _name_to_id(self, name: str) -> str | None:
        sources = (self.coordinator.data or {}).get("value_sources") or []
        for s in sources:
            if s["name"] == name:
                return s["id"]
        return None
--- a/custom_components/wled_screen_controller/translations/en.json
+++ b/custom_components/wled_screen_controller/translations/en.json
@@ -31,6 +31,11 @@
        "name": "{scene_name}"
      }
    },
    "light": {
      "api_input_light": {
        "name": "Light"
      }
    },
    "switch": {
      "processing": {
        "name": "Processing"
@@ -58,9 +63,12 @@
        "name": "Brightness"
      }
    },
-    "light": {
+    "select": {
-      "light": {
+      "color_strip_source": {
-        "name": "Light"
+        "name": "Color Strip Source"
      },
      "brightness_source": {
        "name": "Brightness Source"
      }
    }
  }
--- a/custom_components/wled_screen_controller/translations/ru.json
+++ b/custom_components/wled_screen_controller/translations/ru.json
@@ -31,6 +31,11 @@
        "name": "{scene_name}"
      }
    },
    "light": {
      "api_input_light": {
        "name": "Подсветка"
      }
    },
    "switch": {
      "processing": {
        "name": "Обработка"
@@ -58,9 +63,12 @@
        "name": "Яркость"
      }
    },
-    "light": {
+    "select": {
-      "light": {
+      "color_strip_source": {
-        "name": "Подсветка"
+        "name": "Источник цветовой полосы"
      },
      "brightness_source": {
        "name": "Источник яркости"
      }
    }
  }
--- 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/plans/demo-mode/CONTEXT.md
+++ b/plans/demo-mode/CONTEXT.md
@@ -0,0 +1,30 @@
 # Feature Context: Demo Mode
 ## Current State
 Starting implementation. No changes made yet.
 ## Key Architecture Notes
 - `EngineRegistry` (class-level dict) holds capture engines, auto-registered in `capture_engines/__init__.py`
 - `AudioEngineRegistry` (class-level dict) holds audio engines, auto-registered in `audio/__init__.py`
 - `LEDDeviceProvider` instances registered via `register_provider()` in `led_client.py`
 - Already has `MockDeviceProvider` + `MockClient` (device type "mock") for testing
 - Config is `pydantic_settings.BaseSettings` in `config.py`, loaded from YAML + env vars
 - Frontend header in `templates/index.html` line 27-31: title + version badge
 - Frontend bundle: `cd server && npm run build` (esbuild)
 - Data stored as JSON in `data/` directory, paths configured via `StorageConfig`
 ## Temporary Workarounds
 - None yet
 ## Cross-Phase Dependencies
 - Phase 1 (config flag) is foundational — all other phases depend on `is_demo_mode()`
 - Phase 2 & 3 (engines) can be done independently of each other
 - Phase 4 (seed data) depends on knowing what entities to create, which is informed by phases 2-3
 - Phase 5 (frontend) depends on the system info API field from phase 1
 - Phase 6 (engine resolution) depends on engines existing from phases 2-3
 ## Implementation Notes
 - Demo mode activated via `WLED_DEMO=true` env var or `demo: true` in YAML config
 - Isolated data directory `data/demo/` keeps demo entities separate from real config
 - Demo engines use `ENGINE_TYPE = "demo"` and are always registered but return `is_available() = True` only in demo mode
 - The existing `MockDeviceProvider`/`MockClient` can be reused or extended for demo device output
--- a/plans/demo-mode/PLAN.md
+++ b/plans/demo-mode/PLAN.md
@@ -0,0 +1,44 @@
 # Feature: Demo Mode
 **Branch:** `feature/demo-mode`
 **Base branch:** `master`
 **Created:** 2026-03-20
 **Status:** 🟡 In Progress
 **Strategy:** Big Bang
 **Mode:** Automated
 **Execution:** Orchestrator
 ## Summary
 Add a demo mode that allows users to explore and test the app without real hardware. Virtual capture engines, audio engines, and device providers replace real hardware. An isolated data directory with seed data provides a fully populated sandbox. A visual indicator in the UI makes it clear the app is running in demo mode.
 ## Build & Test Commands
 - **Build (frontend):** `cd server && npm run build`
 - **Typecheck (frontend):** `cd server && npm run typecheck`
 - **Test (backend):** `cd server && python -m pytest ../tests/ -x`
 - **Server start:** `cd server && python -m wled_controller.main`
 ## Phases
 - [x] Phase 1: Demo Mode Config & Flag [domain: backend] → [subplan](./phase-1-config-flag.md)
 - [x] Phase 2: Virtual Capture Engine [domain: backend] → [subplan](./phase-2-virtual-capture-engine.md)
 - [x] Phase 3: Virtual Audio Engine [domain: backend] → [subplan](./phase-3-virtual-audio-engine.md)
 - [x] Phase 4: Demo Device Provider & Seed Data [domain: backend] → [subplan](./phase-4-demo-device-seed-data.md)
 - [x] Phase 5: Frontend Demo Indicator & Sandbox UX [domain: fullstack] → [subplan](./phase-5-frontend-demo-ux.md)
 - [x] Phase 6: Demo-only Engine Resolution [domain: backend] → [subplan](./phase-6-engine-resolution.md)
 ## Phase Progress Log
 | Phase | Domain | Status | Review | Build | Committed |
 |-------|--------|--------|--------|-------|-----------|
 | Phase 1: Config & Flag | backend | ✅ Done | ✅ | ✅ | ⬜ |
 | Phase 2: Virtual Capture Engine | backend | ✅ Done | ✅ | ✅ | ⬜ |
 | Phase 3: Virtual Audio Engine | backend | ✅ Done | ✅ | ✅ | ⬜ |
 | Phase 4: Demo Device & Seed Data | backend | ✅ Done | ✅ | ✅ | ⬜ |
 | Phase 5: Frontend Demo UX | fullstack | ✅ Done | ✅ | ✅ | ⬜ |
 | Phase 6: Engine Resolution | backend | ✅ Done | ✅ | ✅ | ⬜ |
 ## Final Review
 - [ ] Comprehensive code review
 - [ ] Full build passes
 - [ ] Full test suite passes
 - [ ] Merged to `master`
--- a/plans/demo-mode/phase-1-config-flag.md
+++ b/plans/demo-mode/phase-1-config-flag.md
@@ -0,0 +1,42 @@
 # Phase 1: Demo Mode Config & Flag
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 ## Objective
 Add a `demo` boolean flag to the application configuration and expose it to the frontend via the system info API. When demo mode is active, the server uses an isolated data directory so demo entities don't pollute real user data.
 ## Tasks
 - [ ] Task 1: Add `demo: bool = False` field to `Config` class in `config.py`
 - [ ] Task 2: Add a module-level helper `is_demo_mode() -> bool` in `config.py` for easy import
 - [ ] Task 3: Modify `StorageConfig` path resolution: when `demo=True`, prefix all storage paths with `data/demo/` instead of `data/`
 - [ ] Task 4: Expose `demo_mode: bool` in the existing `GET /api/v1/system/info` endpoint response
 - [ ] Task 5: Add `WLED_DEMO=true` env var support (already handled by pydantic-settings env prefix `WLED_`)
 ## Files to Modify/Create
 - `server/src/wled_controller/config.py` — Add `demo` field, `is_demo_mode()` helper, storage path override
 - `server/src/wled_controller/api/routes/system.py` — Add `demo_mode` to system info response
 - `server/src/wled_controller/api/schemas/system.py` — Add `demo_mode` field to response schema
 ## Acceptance Criteria
 - `Config(demo=True)` is accepted; default is `False`
 - `WLED_DEMO=true` activates demo mode
 - `is_demo_mode()` returns the correct value
 - When demo mode is on, all storage files resolve under `data/demo/`
 - `GET /api/v1/system/info` includes `demo_mode: true/false`
 ## Notes
 - The env var will be `WLED_DEMO` because of `env_prefix="WLED_"` in pydantic-settings
 - Storage path override should happen at `Config` construction time, not lazily
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/plans/demo-mode/phase-2-virtual-capture-engine.md
+++ b/plans/demo-mode/phase-2-virtual-capture-engine.md
@@ -0,0 +1,48 @@
 # Phase 2: Virtual Capture Engine
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 ## Objective
 Create a `DemoCaptureEngine` that provides virtual displays and produces animated test pattern frames, allowing screen capture workflows to function in demo mode without real monitors.
 ## Tasks
 - [ ] Task 1: Create `server/src/wled_controller/core/capture_engines/demo_engine.py` with `DemoCaptureEngine` and `DemoCaptureStream`
 - [ ] Task 2: `DemoCaptureEngine.ENGINE_TYPE = "demo"`, `ENGINE_PRIORITY = 1000` (highest in demo mode)
 - [ ] Task 3: `is_available()` returns `True` only when `is_demo_mode()` is True
 - [ ] Task 4: `get_available_displays()` returns 3 virtual displays:
  - "Demo Display 1080p" (1920×1080)
  - "Demo Ultrawide" (3440×1440)
  - "Demo Portrait" (1080×1920)
 - [ ] Task 5: `DemoCaptureStream.capture_frame()` produces animated test patterns:
  - Horizontally scrolling rainbow gradient (simple, visually clear)
  - Uses `time.time()` for animation so frames change over time
  - Returns proper `ScreenCapture` with RGB numpy array
 - [ ] Task 6: Register `DemoCaptureEngine` in `capture_engines/__init__.py`
 ## Files to Modify/Create
 - `server/src/wled_controller/core/capture_engines/demo_engine.py` — New file: DemoCaptureEngine + DemoCaptureStream
 - `server/src/wled_controller/core/capture_engines/__init__.py` — Register DemoCaptureEngine
 ## Acceptance Criteria
 - `DemoCaptureEngine.is_available()` is True only in demo mode
 - Virtual displays appear in the display list API when in demo mode
 - `capture_frame()` returns valid RGB frames that change over time
 - Engine is properly registered in EngineRegistry
 ## Notes
 - Test patterns should be computationally cheap (no heavy image processing)
 - Use numpy operations for pattern generation (vectorized, fast)
 - Frame dimensions must match the virtual display dimensions
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/plans/demo-mode/phase-3-virtual-audio-engine.md
+++ b/plans/demo-mode/phase-3-virtual-audio-engine.md
@@ -0,0 +1,47 @@
 # Phase 3: Virtual Audio Engine
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 ## Objective
 Create a `DemoAudioEngine` that provides virtual audio devices and produces synthetic audio data, enabling audio-reactive visualizations in demo mode.
 ## Tasks
 - [ ] Task 1: Create `server/src/wled_controller/core/audio/demo_engine.py` with `DemoAudioEngine` and `DemoAudioCaptureStream`
 - [ ] Task 2: `DemoAudioEngine.ENGINE_TYPE = "demo"`, `ENGINE_PRIORITY = 1000`
 - [ ] Task 3: `is_available()` returns `True` only when `is_demo_mode()` is True
 - [ ] Task 4: `enumerate_devices()` returns 2 virtual devices:
  - "Demo Microphone" (input, not loopback)
  - "Demo System Audio" (loopback)
 - [ ] Task 5: `DemoAudioCaptureStream` implements:
  - `channels = 2`, `sample_rate = 44100`, `chunk_size = 1024`
  - `read_chunk()` produces synthetic audio: a mix of sine waves with slowly varying frequencies to simulate music-like beat patterns
  - Returns proper float32 ndarray
 - [ ] Task 6: Register `DemoAudioEngine` in `audio/__init__.py`
 ## Files to Modify/Create
 - `server/src/wled_controller/core/audio/demo_engine.py` — New file: DemoAudioEngine + DemoAudioCaptureStream
 - `server/src/wled_controller/core/audio/__init__.py` — Register DemoAudioEngine
 ## Acceptance Criteria
 - `DemoAudioEngine.is_available()` is True only in demo mode
 - Virtual audio devices appear in audio device enumeration when in demo mode
 - `read_chunk()` returns valid float32 audio data that varies over time
 - Audio analyzer produces non-trivial frequency band data from the synthetic signal
 ## Notes
 - Synthetic audio should produce interesting FFT results (multiple frequencies, amplitude modulation)
 - Keep it computationally lightweight
 - Must conform to `AudioCaptureStreamBase` interface exactly
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/plans/demo-mode/phase-4-demo-device-seed-data.md
+++ b/plans/demo-mode/phase-4-demo-device-seed-data.md
@@ -0,0 +1,54 @@
 # Phase 4: Demo Device Provider & Seed Data
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 ## Objective
 Create a demo device provider that exposes discoverable virtual LED devices, and build a seed data generator that populates the demo data directory with sample entities on first run.
 ## Tasks
 - [ ] Task 1: Create `server/src/wled_controller/core/devices/demo_provider.py` — `DemoDeviceProvider` extending `LEDDeviceProvider`:
  - `device_type = "demo"`
  - `capabilities = {"manual_led_count", "power_control", "brightness_control", "static_color"}`
  - `create_client()` returns a `MockClient` (reuse existing)
  - `discover()` returns 3 pre-defined virtual devices:
    - "Demo LED Strip" (60 LEDs, ip="demo-strip")
    - "Demo LED Matrix" (256 LEDs / 16×16, ip="demo-matrix")
    - "Demo LED Ring" (24 LEDs, ip="demo-ring")
  - `check_health()` always returns online with simulated ~2ms latency
  - `validate_device()` returns `{"led_count": <from url>}`
 - [ ] Task 2: Register `DemoDeviceProvider` in `led_client.py` `_register_builtin_providers()`
 - [ ] Task 3: Create `server/src/wled_controller/core/demo_seed.py` — seed data generator:
  - Function `seed_demo_data(storage_config: StorageConfig)` that checks if demo data dir is empty and populates it
  - Seed entities: 3 devices (matching discover results), 2 output targets, 2 picture sources (using demo engine), 2 CSS sources (gradient + color_cycle), 1 audio source (using demo engine), 1 scene preset, 1 automation
  - Use proper ID formats matching existing conventions (e.g., `dev_<hex>`, `tgt_<hex>`, etc.)
 - [ ] Task 4: Call `seed_demo_data()` during server startup in `main.py` when demo mode is active (before stores are loaded)
 ## Files to Modify/Create
 - `server/src/wled_controller/core/devices/demo_provider.py` — New: DemoDeviceProvider
 - `server/src/wled_controller/core/devices/led_client.py` — Register DemoDeviceProvider
 - `server/src/wled_controller/core/demo_seed.py` — New: seed data generator
 - `server/src/wled_controller/main.py` — Call seed on demo startup
 ## Acceptance Criteria
 - Demo devices appear in discovery results when in demo mode
 - Seed data populates `data/demo/` with valid JSON files on first demo run
 - Subsequent demo runs don't overwrite existing demo data
 - All seeded entities load correctly in stores
 ## Notes
 - Seed data must match the exact schema expected by each store (look at existing JSON files for format)
 - Use the entity dataclass `to_dict()` / store patterns to generate valid data
 - Demo discovery should NOT appear when not in demo mode
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/plans/demo-mode/phase-5-frontend-demo-ux.md
+++ b/plans/demo-mode/phase-5-frontend-demo-ux.md
@@ -0,0 +1,50 @@
 # Phase 5: Frontend Demo Indicator & Sandbox UX
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** fullstack
 ## Objective
 Add visual indicators in the frontend that clearly communicate demo mode status to the user, including a badge, dismissible banner, and engine labeling.
 ## Tasks
 - [ ] Task 1: Add `demo_mode` field to system info API response schema (if not already done in Phase 1)
 - [ ] Task 2: In frontend initialization (`app.ts` or `state.ts`), fetch system info and store `demoMode` in app state
 - [ ] Task 3: Add `<span class="demo-badge" id="demo-badge" style="display:none">DEMO</span>` next to app title in `index.html` header
 - [ ] Task 4: CSS for `.demo-badge`: amber/yellow pill shape, subtle pulse animation, clearly visible but not distracting
 - [ ] Task 5: On app load, if `demoMode` is true: show badge, set `document.body.dataset.demo = 'true'`
 - [ ] Task 6: Add a dismissible demo banner at the top of the page: "You're in demo mode — all devices and data are virtual. No real hardware is used." with a dismiss (×) button. Store dismissal in localStorage.
 - [ ] Task 7: Add i18n keys for demo badge and banner text in `en.json`, `ru.json`, `zh.json`
 - [ ] Task 8: In engine/display dropdowns, demo engines should display with "Demo: " prefix for clarity
 ## Files to Modify/Create
 - `server/src/wled_controller/templates/index.html` — Demo badge + banner HTML
 - `server/src/wled_controller/static/css/app.css` — Demo badge + banner styles
 - `server/src/wled_controller/static/js/app.ts` — Demo mode detection and UI toggle
 - `server/src/wled_controller/static/js/core/state.ts` — Store demo mode flag
 - `server/src/wled_controller/static/locales/en.json` — i18n keys
 - `server/src/wled_controller/static/locales/ru.json` — i18n keys
 - `server/src/wled_controller/static/locales/zh.json` — i18n keys
 ## Acceptance Criteria
 - Demo badge visible next to "LED Grab" title when in demo mode
 - Demo badge hidden when not in demo mode
 - Banner appears on first demo visit, can be dismissed, stays dismissed across refreshes
 - Engine dropdowns clearly label demo engines
 - All text is localized
 ## Notes
 - Badge should use `--warning-color` or a custom amber for the pill
 - Banner should be a thin strip, not intrusive
 - `localStorage` key: `demo-banner-dismissed`
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/plans/demo-mode/phase-6-engine-resolution.md
+++ b/plans/demo-mode/phase-6-engine-resolution.md
@@ -0,0 +1,46 @@
 # Phase 6: Demo-only Engine Resolution
 **Status:** ⬜ Not Started
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 ## Objective
 Ensure demo engines are the primary/preferred engines in demo mode, and are hidden when not in demo mode. This makes demo mode act as a "virtual platform" where only demo engines resolve.
 ## Tasks
 - [ ] Task 1: Modify `EngineRegistry.get_available_engines()` to filter out engines with `ENGINE_TYPE == "demo"` when not in demo mode (they report `is_available()=False` anyway, but belt-and-suspenders)
 - [ ] Task 2: Modify `AudioEngineRegistry.get_available_engines()` similarly
 - [ ] Task 3: In demo mode, `get_best_available_engine()` should return the demo engine (already handled by priority=1000, but verify)
 - [ ] Task 4: Modify the `GET /api/v1/config/displays` endpoint: in demo mode, default to demo engine displays if no engine_type specified
 - [ ] Task 5: Modify the audio engine listing endpoint similarly
 - [ ] Task 6: Ensure `DemoDeviceProvider.discover()` only returns devices when in demo mode
 - [ ] Task 7: End-to-end verification: start server in demo mode, verify only demo engines/devices appear in API responses
 ## Files to Modify/Create
 - `server/src/wled_controller/core/capture_engines/factory.py` — Filter demo engines
 - `server/src/wled_controller/core/audio/factory.py` — Filter demo engines
 - `server/src/wled_controller/api/routes/system.py` — Display endpoint defaults
 - `server/src/wled_controller/api/routes/audio_templates.py` — Audio engine listing
 - `server/src/wled_controller/core/devices/demo_provider.py` — Guard discover()
 ## Acceptance Criteria
 - In demo mode: demo engines are primary, real engines may also be listed but demo is default
 - Not in demo mode: demo engines are completely hidden from all API responses
 - Display list defaults to demo displays in demo mode
 - Audio device list defaults to demo devices in demo mode
 ## Notes
 - This is the "demo OS identifier" concept — demo mode acts as a virtual platform
 - Be careful not to break existing behavior when demo=False (default)
 - The demo engines already have `is_available() = is_demo_mode()`, so the main concern is UI defaults
 ## Review Checklist
 - [ ] All tasks completed
 - [ ] Code follows project conventions
 - [ ] No unintended side effects
 - [ ] Build passes
 - [ ] Tests pass (new + existing)
 ## Handoff to Next Phase
 <!-- Filled in after completion -->
--- a/server/.env.example
+++ b/server/.env.example
@@ -0,0 +1,54 @@
 # WLED Screen Controller — Environment Variables
 # Copy this file to .env and adjust values as needed.
 # All variables use the WLED_ prefix with __ (double underscore) as the nesting delimiter.
 # ── Server ──────────────────────────────────────────────
 # WLED_SERVER__HOST=0.0.0.0        # Listen address (default: 0.0.0.0)
 # WLED_SERVER__PORT=8080            # Listen port (default: 8080)
 # WLED_SERVER__LOG_LEVEL=INFO       # Log level: DEBUG, INFO, WARNING, ERROR (default: INFO)
 # WLED_SERVER__CORS_ORIGINS=["*"]   # JSON array of allowed CORS origins
 # ── Authentication ──────────────────────────────────────
 # API keys are required. Format: JSON object {"label": "key"}.
 # WLED_AUTH__API_KEYS={"dev": "development-key-change-in-production"}
 # ── Storage paths ───────────────────────────────────────
 # All paths are relative to the server working directory.
 # WLED_STORAGE__DEVICES_FILE=data/devices.json
 # WLED_STORAGE__TEMPLATES_FILE=data/capture_templates.json
 # WLED_STORAGE__POSTPROCESSING_TEMPLATES_FILE=data/postprocessing_templates.json
 # WLED_STORAGE__PICTURE_SOURCES_FILE=data/picture_sources.json
 # WLED_STORAGE__OUTPUT_TARGETS_FILE=data/output_targets.json
 # WLED_STORAGE__PATTERN_TEMPLATES_FILE=data/pattern_templates.json
 # WLED_STORAGE__COLOR_STRIP_SOURCES_FILE=data/color_strip_sources.json
 # WLED_STORAGE__AUDIO_SOURCES_FILE=data/audio_sources.json
 # WLED_STORAGE__AUDIO_TEMPLATES_FILE=data/audio_templates.json
 # WLED_STORAGE__VALUE_SOURCES_FILE=data/value_sources.json
 # WLED_STORAGE__AUTOMATIONS_FILE=data/automations.json
 # WLED_STORAGE__SCENE_PRESETS_FILE=data/scene_presets.json
 # WLED_STORAGE__COLOR_STRIP_PROCESSING_TEMPLATES_FILE=data/color_strip_processing_templates.json
 # WLED_STORAGE__SYNC_CLOCKS_FILE=data/sync_clocks.json
 # ── MQTT (optional) ────────────────────────────────────
 # WLED_MQTT__ENABLED=false
 # WLED_MQTT__BROKER_HOST=localhost
 # WLED_MQTT__BROKER_PORT=1883
 # WLED_MQTT__USERNAME=
 # WLED_MQTT__PASSWORD=
 # WLED_MQTT__CLIENT_ID=ledgrab
 # WLED_MQTT__BASE_TOPIC=ledgrab
 # ── Logging ─────────────────────────────────────────────
 # WLED_LOGGING__FORMAT=json          # json or text (default: json)
 # WLED_LOGGING__FILE=logs/wled_controller.log
 # WLED_LOGGING__MAX_SIZE_MB=100
 # WLED_LOGGING__BACKUP_COUNT=5
 # ── Demo mode ───────────────────────────────────────────
 # WLED_DEMO=false                    # Enable demo mode (uses data/demo/ directory)
 # ── Config file override ───────────────────────────────
 # WLED_CONFIG_PATH=                  # Absolute path to a YAML config file (overrides all above)
 # ── Docker Compose extras (not part of WLED_ prefix) ───
 # DISPLAY=:0                         # X11 display for Linux screen capture
--- a/server/CLAUDE.md
+++ b/server/CLAUDE.md
@@ -1,212 +1,76 @@
 # Claude Instructions for WLED Screen Controller Server
-## Development Workflow
+## Project Structure
-### Server Restart Policy
+- `src/wled_controller/main.py` — FastAPI application entry point
 - `src/wled_controller/api/routes/` — REST API endpoints (one file per entity)
 - `src/wled_controller/api/schemas/` — Pydantic request/response models (one file per entity)
 - `src/wled_controller/core/` — Core business logic (capture, devices, audio, processing, automations)
 - `src/wled_controller/storage/` — Data models (dataclasses) and JSON persistence stores
 - `src/wled_controller/utils/` — Utility functions (logging, monitor detection)
 - `src/wled_controller/static/` — Frontend files (TypeScript, CSS, locales)
 - `src/wled_controller/templates/` — Jinja2 HTML templates
 - `config/` — Configuration files (YAML)
 - `data/` — Runtime data (JSON stores, persisted state)
-**IMPORTANT**: When making changes to server code (Python files in `src/wled_controller/`), you MUST restart the server if it's currently running to ensure the changes take effect.
+## Entity & Storage Pattern
-**NOTE**: Auto-reload is currently disabled (`reload=False` in `main.py`) due to watchfiles causing an infinite reload loop. Changes to server code will NOT be automatically picked up - manual server restart is required.
+Each entity follows: dataclass model (`storage/`) + JSON store (`storage/*_store.py`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`).
 #### When to restart:
 - After modifying API routes (`api/routes.py`, `api/schemas.py`)
 - After updating core logic (`core/*.py`)
 - After changing configuration (`config.py`)
 - After modifying utilities (`utils/*.py`)
 - After updating data models or database schemas
 #### How to check if server is running:
 ```bash
 # Look for running Python processes with wled_controller
 ps aux | grep wled_controller
 # Or check for processes listening on port 8080
 netstat -an | grep 8080
 ```
 #### How to restart:
 1. **Find the task ID** of the running server (look for background bash tasks in conversation)
 2. **Stop the server** using TaskStop with the task ID
 3. **Check for port conflicts** (port 8080 may still be in use):
   ```bash
   netstat -ano | findstr :8080
   ```
   If a process is still using port 8080, kill it:
   ```bash
   powershell -Command "Stop-Process -Id <PID> -Force"
   ```
 4. **Start a new server instance** in the background:
   ```bash
   cd server && python -m wled_controller.main
   ```
   Use `run_in_background: true` parameter in Bash tool
 5. **Wait 3 seconds** for server to initialize:
   ```bash
   sleep 3
   ```
 6. **Verify startup** by reading the output file:
   - Look for "Uvicorn running on http://0.0.0.0:8080"
   - Check for any errors in stderr
   - Verify "Application startup complete" message
 **Common Issues:**
 - **Port 8080 in use**: Old process didn't terminate cleanly - kill it manually
 - **Module import errors**: Check that all Python files are syntactically correct
 - **Permission errors**: Ensure file permissions allow Python to execute
 #### Files that DON'T require restart:
 - Static files (`static/*.html`, `static/*.css`, `static/*.js`) - but you **MUST rebuild the bundle** after changes: `cd server && npm run build`
 - Locale files (`static/locales/*.json`) - loaded by frontend
 - Documentation files (`*.md`)
 - Configuration files in `config/` if server supports hot-reload (check implementation)
 ### Git Commit and Push Policy
 **CRITICAL**: NEVER commit OR push code changes without explicit user approval.
 #### Rules
 - You MUST NOT create commits without explicit user instruction
 - You MUST NOT push commits unless explicitly instructed by the user
 - Wait for the user to review changes and ask you to commit
 - If the user says "commit", create a commit but DO NOT push
 - If the user says "commit and push", you may push after committing
 - Always wait for explicit permission before any commit or push operation
 #### Workflow
 1. Make changes to code
 2. **STOP and WAIT** - inform the user of changes and wait for instruction
 3. Only create commit when user explicitly requests it (e.g., "commit", "create a commit")
 4. **STOP and WAIT** - do not push
 5. Only push when user explicitly requests it (e.g., "push", "commit and push", "push to remote")
 ### Testing Changes
 After restarting the server with new code:
 1. Test the modified endpoints/functionality
 2. Check browser console for any JavaScript errors
 3. Verify API responses match updated schemas
 4. Test with different locales if i18n was modified
 ## Project Structure Notes
 - `src/wled_controller/main.py` - FastAPI application entry point
 - `src/wled_controller/api/` - REST API endpoints and schemas
 - `src/wled_controller/core/` - Core business logic (screen capture, WLED client, processing)
 - `src/wled_controller/utils/` - Utility functions (logging, monitor detection)
 - `src/wled_controller/static/` - Frontend files (HTML, CSS, JS, locales)
 - `config/` - Configuration files (YAML)
 - `data/` - Runtime data (devices.json, persistence)
 ## Common Tasks
 ### Adding a new API endpoint:
 1. Add route to `api/routes.py`
 2. Define request/response schemas in `api/schemas.py`
 3. **Restart the server**
 4. Test the endpoint via `/docs` (Swagger UI)
 ### Adding a new field to existing API:
 1. Update Pydantic schema in `api/schemas.py`
 2. Update corresponding dataclass (if applicable)
 3. Update backend logic to populate the field
 4. **Restart the server**
 5. Update frontend to display the new field
 ### Modifying display/monitor detection:
 1. Update functions in `utils/monitor_names.py` or `core/screen_capture.py`
 2. **Restart the server**
 3. Test with `GET /api/v1/config/displays`
 ### Modifying server login:
 1. Update the logic.
 2. **Restart the server**
 ### Adding translations:
 1. Add keys to `static/locales/en.json` and `static/locales/ru.json`
 2. Add `data-i18n` attributes to HTML elements in `static/index.html`
 3. Use `t('key')` function in `static/app.js` for dynamic content
 4. No server restart needed (frontend only)
 ## Frontend UI Patterns
 ### Entity Cards
 All entity cards (devices, targets, CSS sources, streams, scenes, automations, etc.) **must support clone functionality**. Clone buttons use the `ICON_CLONE` (📋) icon in `.card-actions`.
 **Clone pattern**: Clone must open the entity's add/create modal with fields prefilled from the cloned item. It must **never** silently create a duplicate — the user should review and confirm.
 Implementation:
 1. Export a `cloneMyEntity(id)` function that fetches (or finds in cache) the entity data
 2. Call the add/create modal function, passing the entity data as `cloneData`
 3. In the modal opener, detect clone mode (no ID + cloneData present) and prefill all fields
 4. Append `' (Copy)'` to the name
 5. Set the modal title to the "add" variant (not "edit")
 6. The save action creates a new entity (POST), not an update (PUT)
 ```javascript
 export async function cloneMyEntity(id) {
    const entity = myCache.data.find(e => e.id === id);
    if (!entity) return;
    showMyEditor(null, entity);  // null id = create mode, entity = cloneData
 }
 ```
 Register the clone function in `app.js` window exports so inline `onclick` handlers can call it.
 ### Modal Dialogs
 **IMPORTANT**: All modal dialogs must follow these standards for consistent UX:
 #### Backdrop Click Behavior
 All modals MUST close when the user clicks outside the dialog (on the backdrop). Implement this by adding a click handler that checks if the clicked element is the modal backdrop itself:
 ```javascript
 // Show modal
 const modal = document.getElementById('my-modal');
 modal.style.display = 'flex';
 // Add backdrop click handler to close modal
 modal.onclick = function(event) {
    if (event.target === modal) {
        closeMyModal();
    }
 };
 ```
 **Where to add**: In every function that shows a modal (e.g., `showAddTemplateModal()`, `editTemplate()`, `showTestTemplateModal()`).
 #### Close Button Requirement
 Each modal dialog that has a "Cancel" button MUST also have a cross (×) close button at the top-right corner of the dialog. This provides users with multiple intuitive ways to dismiss the dialog:
 1. Click the backdrop (outside the dialog)
 2. Click the × button (top-right corner)
 3. Click the Cancel button (bottom of dialog)
 4. Press Escape key (if implemented)
 **HTML Structure**:
 ```html
 <div class="modal-content">
    <button class="close-btn" onclick="closeMyModal()">&times;</button>
    <h2>Dialog Title</h2>
    <!-- dialog content -->
    <div class="modal-actions">
        <button onclick="closeMyModal()">Cancel</button>
        <button onclick="submitAction()">Submit</button>
    </div>
 </div>
 ```
 **CSS Requirements**:
 - Close button should be positioned absolutely at top-right
 - Should be easily clickable (min 24px × 24px hit area)
 - Should have clear hover state
 ## Authentication
-Server uses API key authentication. Keys are configured in:
+Server uses API key authentication via Bearer token in `Authorization` header.
 - `config/default_config.yaml` under `auth.api_keys`
 - Or via environment variables: `WLED_AUTH__API_KEYS`
-For development, ensure at least one API key is configured or the server won't start.
+- Config: `config/default_config.yaml` under `auth.api_keys`
 - Env var: `WLED_AUTH__API_KEYS`
 - Dev key: `development-key-change-in-production`
 ## Common Tasks
 ### Adding a new API endpoint
 1. Create route file in `api/routes/`
 2. Define request/response schemas in `api/schemas/`
 3. Register the router in `main.py`
 4. Restart the server
 5. Test via `/docs` (Swagger UI)
 ### Adding a new field to existing API
 1. Update Pydantic schema in `api/schemas/`
 2. Update corresponding dataclass in `storage/`
 3. Update backend logic to populate the field
 4. Restart the server
 5. Update frontend to display the new field
 6. Rebuild bundle: `cd server && npm run build`
 ### Adding translations
 1. Add keys to `static/locales/en.json`, `static/locales/ru.json`, and `static/locales/zh.json`
 2. Add `data-i18n` attributes to HTML elements in `templates/`
 3. Use `t('key')` in TypeScript modules (`static/js/`)
 4. No server restart needed (frontend only), but rebuild bundle if JS changed
 ### Modifying display/monitor detection
 1. Update functions in `utils/monitor_names.py` or `core/screen_capture.py`
 2. Restart the server
 3. Test with `GET /api/v1/config/displays`
 ## Testing
 ```bash
 cd server && pytest                    # Run all tests
 cd server && pytest --cov              # With coverage report
 cd server && pytest tests/test_api.py  # Single test file
 ```
 Tests are in `server/tests/`. Config in `pyproject.toml` under `[tool.pytest]`.
 ## Frontend Conventions
 For all frontend conventions (CSS variables, UI patterns, modals, localization, icons, bundling), see [contexts/frontend.md](../contexts/frontend.md).
 ## Server Operations
 For restart procedures, server modes, and demo mode checklist, see [contexts/server-operations.md](../contexts/server-operations.md).
--- a/server/Dockerfile
+++ b/server/Dockerfile
@@ -1,12 +1,28 @@
-FROM python:3.11-slim
+## Stage 1: Build frontend bundle
 FROM node:20.18-slim AS frontend
 WORKDIR /build
 COPY package.json package-lock.json* ./
 RUN npm ci --ignore-scripts
 COPY esbuild.mjs tsconfig.json ./
 COPY src/wled_controller/static/ ./src/wled_controller/static/
 RUN npm run build
 ## Stage 2: Python application
 FROM python:3.11.11-slim AS runtime
 LABEL maintainer="Alexei Dolgolyov <dolgolyov.alexei@gmail.com>"
-LABEL description="WLED Screen Controller - Ambient lighting based on screen content"
+LABEL org.opencontainers.image.title="LED Grab"
 LABEL org.opencontainers.image.description="Ambient lighting system that captures screen content and drives LED strips in real time"
 LABEL org.opencontainers.image.version="0.2.0"
 LABEL org.opencontainers.image.url="https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"
 LABEL org.opencontainers.image.source="https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"
 LABEL org.opencontainers.image.licenses="MIT"
 WORKDIR /app
-# Install system dependencies for screen capture
+# Install system dependencies for screen capture and health check
-RUN apt-get update && apt-get install -y \
+RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    libxcb1 \
    libxcb-randr0 \
    libxcb-shm0 \
@@ -14,21 +30,35 @@ RUN apt-get update && apt-get install -y \
    libxcb-shape0 \
    && rm -rf /var/lib/apt/lists/*
-# Copy project files and install Python dependencies
+# Install Python dependencies first (layer caching optimization).
 # Copy pyproject.toml with a minimal package stub so pip can resolve deps.
 # The real source is copied afterward, keeping the dep layer cached.
 COPY pyproject.toml .
 RUN mkdir -p src/wled_controller && touch src/wled_controller/__init__.py \
    && pip install --no-cache-dir ".[notifications]" \
    && rm -rf src/wled_controller
 # Copy source code and config (invalidates cache only when source changes)
 COPY src/ ./src/
 COPY config/ ./config/
 RUN pip install --no-cache-dir ".[notifications]"
-# Create directories for data and logs
+# Copy built frontend bundle from stage 1
-RUN mkdir -p /app/data /app/logs
+COPY --from=frontend /build/src/wled_controller/static/dist/ ./src/wled_controller/static/dist/
 # Create non-root user for security
 RUN groupadd --gid 1000 ledgrab \
    && useradd --uid 1000 --gid ledgrab --shell /bin/bash --create-home ledgrab \
    && mkdir -p /app/data /app/logs \
    && chown -R ledgrab:ledgrab /app
 USER ledgrab
 # Expose API port
 EXPOSE 8080
 # Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
-    CMD python -c "import httpx; httpx.get('http://localhost:8080/health', timeout=5.0)" || exit 1
+    CMD curl -f http://localhost:8080/health || exit 1
 # Set Python path
 ENV PYTHONPATH=/app/src
--- a/server/README.md
+++ b/server/README.md
@@ -188,4 +188,4 @@ MIT - see [../LICENSE](../LICENSE)
 ## Support
 - 📖 [Full Documentation](../docs/)
- 🐛 [Issues](https://github.com/yourusername/wled-screen-controller/issues)
+- 🐛 [Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues)
--- a/server/config/default_config.yaml
+++ b/server/config/default_config.yaml
@@ -2,8 +2,10 @@ server:
  host: "0.0.0.0"
  port: 8080
  log_level: "INFO"
  # CORS: restrict to localhost by default.
  # For LAN access, add your machine's IP, e.g. "http://192.168.1.100:8080"
  cors_origins:
-    - "*"
+    - "http://localhost:8080"
 auth:
  # API keys are REQUIRED - authentication is always enforced
--- a/server/config/demo_config.yaml
+++ b/server/config/demo_config.yaml
@@ -0,0 +1,36 @@
 # Demo mode configuration
 # Loaded automatically when WLED_DEMO=true is set.
 # Uses isolated data directory (data/demo/) and a pre-configured API key
 # so the demo works out of the box with zero setup.
 demo: true
 server:
  host: "0.0.0.0"
  port: 8081
  log_level: "INFO"
  # CORS: restrict to localhost by default.
  # For LAN access, add your machine's IP, e.g. "http://192.168.1.100:8081"
  cors_origins:
    - "http://localhost:8081"
 auth:
  api_keys:
    demo: "demo"
 storage:
  devices_file: "data/devices.json"
  templates_file: "data/capture_templates.json"
  postprocessing_templates_file: "data/postprocessing_templates.json"
  picture_sources_file: "data/picture_sources.json"
  output_targets_file: "data/output_targets.json"
  pattern_templates_file: "data/pattern_templates.json"
 mqtt:
  enabled: false
 logging:
  format: "text"
  file: "logs/wled_controller.log"
  max_size_mb: 100
  backup_count: 5
--- a/server/docker-compose.yml
+++ b/server/docker-compose.yml
@@ -1,41 +1,54 @@
 version: '3.8'
 services:
  wled-controller:
    build:
      context: .
      dockerfile: Dockerfile
    image: ledgrab:latest
    container_name: wled-screen-controller
    restart: unless-stopped
    ports:
-      - "8080:8080"
+      - "${WLED_PORT:-8080}:8080"
    volumes:
-      # Persist device data
+      # Persist device data and configuration across restarts
      - ./data:/app/data
      # Persist logs
      - ./logs:/app/logs
-      # Mount configuration (optional override)
+      # Mount configuration for easy editing without rebuild
-      - ./config:/app/config
+      - ./config:/app/config:ro
-      # Required for screen capture on Linux
+      # Required for screen capture on Linux (X11)
      - /tmp/.X11-unix:/tmp/.X11-unix:ro
    environment:
-      # Server configuration
+      ## Server
      # Bind address and port (usually no need to change)
      - WLED_SERVER__HOST=0.0.0.0
      - WLED_SERVER__PORT=8080
      - WLED_SERVER__LOG_LEVEL=INFO
      # CORS origins — add your LAN IP for remote access, e.g.:
      #   WLED_SERVER__CORS_ORIGINS=["http://localhost:8080","http://192.168.1.100:8080"]
-      # Display for X11 (Linux only)
+      ## Auth
      # Override the default API key (STRONGLY recommended for production):
      #   WLED_AUTH__API_KEYS__main=your-secure-key-here
      # Generate a key: openssl rand -hex 32
      ## Display (Linux X11 only)
      - DISPLAY=${DISPLAY:-:0}
-      # Processing defaults
+      ## Processing defaults
-      - WLED_PROCESSING__DEFAULT_FPS=30
+      #- WLED_PROCESSING__DEFAULT_FPS=30
-      - WLED_PROCESSING__BORDER_WIDTH=10
+      #- WLED_PROCESSING__BORDER_WIDTH=10
-    # Use host network for screen capture access
+      ## MQTT (optional — for Home Assistant auto-discovery)
-    # network_mode: host  # Uncomment for Linux screen capture
+      #- WLED_MQTT__ENABLED=true
      #- WLED_MQTT__BROKER_HOST=192.168.1.2
      #- WLED_MQTT__BROKER_PORT=1883
      #- WLED_MQTT__USERNAME=
      #- WLED_MQTT__PASSWORD=
    # Uncomment for Linux screen capture (requires host network for X11 access)
    # network_mode: host
    networks:
      - wled-network
--- a/server/esbuild.mjs
+++ b/server/esbuild.mjs
@@ -7,7 +7,7 @@ const watch = process.argv.includes('--watch');
 /** @type {esbuild.BuildOptions} */
 const jsOpts = {
-    entryPoints: [`${srcDir}/js/app.js`],
+    entryPoints: [`${srcDir}/js/app.ts`],
    bundle: true,
    format: 'iife',
    outfile: `${outDir}/app.bundle.js`,
--- a/server/package-lock.json
+++ b/server/package-lock.json
@@ -13,7 +13,8 @@
        "elkjs": "^0.11.1"
      },
      "devDependencies": {
-        "esbuild": "^0.27.4"
+        "esbuild": "^0.27.4",
        "typescript": "^5.9.3"
      }
    },
    "node_modules/@esbuild/aix-ppc64": {
@@ -493,6 +494,19 @@
        "@esbuild/win32-ia32": "0.27.4",
        "@esbuild/win32-x64": "0.27.4"
      }
    },
    "node_modules/typescript": {
      "version": "5.9.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "dev": true,
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
      },
      "engines": {
        "node": ">=14.17"
      }
    }
  },
  "dependencies": {
@@ -729,6 +743,12 @@
        "@esbuild/win32-ia32": "0.27.4",
        "@esbuild/win32-x64": "0.27.4"
      }
    },
    "typescript": {
      "version": "5.9.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "dev": true
    }
  }
 }
--- a/server/package.json
+++ b/server/package.json
@@ -9,13 +9,15 @@
  },
  "scripts": {
    "build": "node esbuild.mjs",
-    "watch": "node esbuild.mjs --watch"
+    "watch": "node esbuild.mjs --watch",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
-    "esbuild": "^0.27.4"
+    "esbuild": "^0.27.4",
    "typescript": "^5.9.3"
  },
  "dependencies": {
    "chart.js": "^4.5.1",
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "wled-screen-controller"
-version = "0.1.0"
+version = "0.2.0"
-description = "WLED ambient lighting controller based on screen content"
+description = "Ambient lighting system that captures screen content and drives LED strips in real time"
 authors = [
    {name = "Alexei Dolgolyov", email = "dolgolyov.alexei@gmail.com"}
 ]
@@ -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",
@@ -56,13 +55,18 @@ dev = [
    "respx>=0.21.1",
    "black>=24.0.0",
    "ruff>=0.6.0",
    "opencv-python-headless>=4.8.0",
 ]
 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)
@@ -75,6 +79,7 @@ perf = [
 [project.urls]
 Homepage = "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"
 Repository = "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed"
 Documentation = "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/src/branch/master/INSTALLATION.md"
 Issues = "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues"
 [tool.setuptools]
--- a/server/src/wled_controller/api/init.py
+++ b/server/src/wled_controller/api/init.py
@@ -3,12 +3,16 @@
 from fastapi import APIRouter
 from .routes.system import router as system_router
 from .routes.backup import router as backup_router
 from .routes.system_settings import router as system_settings_router
 from .routes.devices import router as devices_router
 from .routes.templates import router as templates_router
 from .routes.postprocessing import router as postprocessing_router
 from .routes.picture_sources import router as picture_sources_router
 from .routes.pattern_templates import router as pattern_templates_router
 from .routes.output_targets import router as output_targets_router
 from .routes.output_targets_control import router as output_targets_control_router
 from .routes.output_targets_keycolors import router as output_targets_keycolors_router
 from .routes.color_strip_sources import router as color_strip_sources_router
 from .routes.audio import router as audio_router
 from .routes.audio_sources import router as audio_sources_router
@@ -22,6 +26,8 @@ from .routes.color_strip_processing import router as cspt_router
 router = APIRouter()
 router.include_router(system_router)
 router.include_router(backup_router)
 router.include_router(system_settings_router)
 router.include_router(devices_router)
 router.include_router(templates_router)
 router.include_router(postprocessing_router)
@@ -33,6 +39,8 @@ router.include_router(audio_sources_router)
 router.include_router(audio_templates_router)
 router.include_router(value_sources_router)
 router.include_router(output_targets_router)
 router.include_router(output_targets_control_router)
 router.include_router(output_targets_keycolors_router)
 router.include_router(automations_router)
 router.include_router(scene_presets_router)
 router.include_router(webhooks_router)
--- a/server/src/wled_controller/api/dependencies.py
+++ b/server/src/wled_controller/api/dependencies.py
@@ -4,7 +4,7 @@ Uses a registry dict instead of individual module-level globals.
 All getter function signatures remain unchanged for FastAPI Depends() compatibility.
 """
-from typing import Any, Dict, Type, TypeVar
+from typing import Any, Dict, TypeVar
 from wled_controller.core.processing.processor_manager import ProcessorManager
 from wled_controller.storage import DeviceStore
--- a/server/src/wled_controller/api/routes/_preview_helpers.py
+++ b/server/src/wled_controller/api/routes/_preview_helpers.py
@@ -1,18 +1,16 @@
-"""Shared helpers for WebSocket-based capture test endpoints."""
+"""Shared helpers for WebSocket-based capture preview endpoints."""
 import asyncio
 import base64
 import io
 import secrets
 import threading
 import time
-from typing import Callable, List, Optional
+from typing import Callable, Optional
 import numpy as np
 from PIL import Image
 from starlette.websockets import WebSocket
 from wled_controller.config import get_config
 from wled_controller.core.filters import FilterRegistry, ImagePool
 from wled_controller.utils import get_logger
@@ -45,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)
+        pil_img = pil_img.resize((max_width, new_h), Image.LANCZOS)
-    # RGB → BGR for OpenCV JPEG encoding
+    buf = io.BytesIO()
-    bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+    pil_img.save(buf, format="JPEG", quality=quality)
-    _, buf = cv2.imencode('.jpg', bgr, [cv2.IMWRITE_JPEG_QUALITY, quality])
+    return buf.getvalue()
    return buf.tobytes()
 def _make_thumbnail(pil_image: Image.Image, max_width: int) -> Image.Image:
@@ -124,7 +121,7 @@ async def stream_capture_test(
                    continue
                total_capture_time += t1 - t0
                frame_count += 1
-                # Convert numpy → PIL once in the capture thread
+                # Convert numpy -> PIL once in the capture thread
                if isinstance(capture.image, np.ndarray):
                    latest_frame = Image.fromarray(capture.image)
                else:
--- a/server/src/wled_controller/api/routes/audio_templates.py
+++ b/server/src/wled_controller/api/routes/audio_templates.py
@@ -1,7 +1,6 @@
 """Audio capture template and engine routes."""
 import asyncio
 import json
 from fastapi import APIRouter, HTTPException, Depends, Query
 from starlette.websockets import WebSocket, WebSocketDisconnect
--- a/server/src/wled_controller/api/routes/backup.py
+++ b/server/src/wled_controller/api/routes/backup.py
@@ -0,0 +1,395 @@
 """System routes: backup, restore, export, import, auto-backup.
 Extracted from system.py to keep files under 800 lines.
 """
 import asyncio
 import io
 import json
 import subprocess
 import sys
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
 from fastapi.responses import StreamingResponse
 from wled_controller import __version__
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import get_auto_backup_engine
 from wled_controller.api.schemas.system import (
    AutoBackupSettings,
    AutoBackupStatusResponse,
    BackupFileInfo,
    BackupListResponse,
    RestoreResponse,
 )
 from wled_controller.core.backup.auto_backup import AutoBackupEngine
 from wled_controller.config import get_config
 from wled_controller.utils import atomic_write_json, get_logger
 logger = get_logger(__name__)
 router = APIRouter()
 # ---------------------------------------------------------------------------
 # Configuration backup / restore
 # ---------------------------------------------------------------------------
 # Mapping: logical store name -> StorageConfig attribute name
 STORE_MAP = {
    "devices": "devices_file",
    "capture_templates": "templates_file",
    "postprocessing_templates": "postprocessing_templates_file",
    "picture_sources": "picture_sources_file",
    "output_targets": "output_targets_file",
    "pattern_templates": "pattern_templates_file",
    "color_strip_sources": "color_strip_sources_file",
    "audio_sources": "audio_sources_file",
    "audio_templates": "audio_templates_file",
    "value_sources": "value_sources_file",
    "sync_clocks": "sync_clocks_file",
    "color_strip_processing_templates": "color_strip_processing_templates_file",
    "automations": "automations_file",
    "scene_presets": "scene_presets_file",
 }
 _SERVER_DIR = Path(__file__).resolve().parents[4]
 def _schedule_restart() -> None:
    """Spawn a restart script after a short delay so the HTTP response completes."""
    def _restart():
        import time
        time.sleep(1)
        if sys.platform == "win32":
            subprocess.Popen(
                ["powershell", "-ExecutionPolicy", "Bypass", "-File",
                 str(_SERVER_DIR / "restart.ps1")],
                creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP,
            )
        else:
            subprocess.Popen(
                ["bash", str(_SERVER_DIR / "restart.sh")],
                start_new_session=True,
            )
    threading.Thread(target=_restart, daemon=True).start()
@router.get("/api/v1/system/export/{store_key}", tags=["System"])
 def export_store(store_key: str, _: AuthRequired):
    """Download a single entity store as a JSON file."""
    if store_key not in STORE_MAP:
        raise HTTPException(
            status_code=404,
            detail=f"Unknown store '{store_key}'. Valid keys: {sorted(STORE_MAP.keys())}",
        )
    config = get_config()
    file_path = Path(getattr(config.storage, STORE_MAP[store_key]))
    if file_path.exists():
        with open(file_path, "r", encoding="utf-8") as f:
            data = json.load(f)
    else:
        data = {}
    export = {
        "meta": {
            "format": "ledgrab-partial-export",
            "format_version": 1,
            "store_key": store_key,
            "app_version": __version__,
            "created_at": datetime.now(timezone.utc).isoformat() + "Z",
        },
        "store": data,
    }
    content = json.dumps(export, indent=2, ensure_ascii=False)
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M%S")
    filename = f"ledgrab-{store_key}-{timestamp}.json"
    return StreamingResponse(
        io.BytesIO(content.encode("utf-8")),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.post("/api/v1/system/import/{store_key}", tags=["System"])
 async def import_store(
    store_key: str,
    _: AuthRequired,
    file: UploadFile = File(...),
    merge: bool = Query(False, description="Merge into existing data instead of replacing"),
 ):
    """Upload a partial export file to replace or merge one entity store. Triggers server restart."""
    if store_key not in STORE_MAP:
        raise HTTPException(
            status_code=404,
            detail=f"Unknown store '{store_key}'. Valid keys: {sorted(STORE_MAP.keys())}",
        )
    try:
        raw = await file.read()
        if len(raw) > 10 * 1024 * 1024:
            raise HTTPException(status_code=400, detail="File too large (max 10 MB)")
        payload = json.loads(raw)
    except json.JSONDecodeError as e:
        raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}")
    # Support both full-backup format and partial-export format
    if "stores" in payload and isinstance(payload.get("meta"), dict):
        # Full backup: extract the specific store
        if payload["meta"].get("format") not in ("ledgrab-backup",):
            raise HTTPException(status_code=400, detail="Not a valid LED Grab backup or partial export file")
        stores = payload.get("stores", {})
        if store_key not in stores:
            raise HTTPException(status_code=400, detail=f"Backup does not contain store '{store_key}'")
        incoming = stores[store_key]
    elif isinstance(payload.get("meta"), dict) and payload["meta"].get("format") == "ledgrab-partial-export":
        # Partial export format
        if payload["meta"].get("store_key") != store_key:
            raise HTTPException(
                status_code=400,
                detail=f"File is for store '{payload['meta']['store_key']}', not '{store_key}'",
            )
        incoming = payload.get("store", {})
    else:
        raise HTTPException(status_code=400, detail="Not a valid LED Grab backup or partial export file")
    if not isinstance(incoming, dict):
        raise HTTPException(status_code=400, detail="Store data must be a JSON object")
    config = get_config()
    file_path = Path(getattr(config.storage, STORE_MAP[store_key]))
    def _write():
        if merge and file_path.exists():
            with open(file_path, "r", encoding="utf-8") as f:
                existing = json.load(f)
            if isinstance(existing, dict):
                existing.update(incoming)
                atomic_write_json(file_path, existing)
                return len(existing)
        atomic_write_json(file_path, incoming)
        return len(incoming)
    count = await asyncio.to_thread(_write)
    logger.info(f"Imported store '{store_key}' ({count} entries, merge={merge}). Scheduling restart...")
    _schedule_restart()
    return {
        "status": "imported",
        "store_key": store_key,
        "entries": count,
        "merge": merge,
        "restart_scheduled": True,
        "message": f"Imported {count} entries for '{store_key}'. Server restarting...",
    }
@router.get("/api/v1/system/backup", tags=["System"])
 def backup_config(_: AuthRequired):
    """Download all configuration as a single JSON backup file."""
    config = get_config()
    stores = {}
    for store_key, config_attr in STORE_MAP.items():
        file_path = Path(getattr(config.storage, config_attr))
        if file_path.exists():
            with open(file_path, "r", encoding="utf-8") as f:
                stores[store_key] = json.load(f)
        else:
            stores[store_key] = {}
    backup = {
        "meta": {
            "format": "ledgrab-backup",
            "format_version": 1,
            "app_version": __version__,
            "created_at": datetime.now(timezone.utc).isoformat() + "Z",
            "store_count": len(stores),
        },
        "stores": stores,
    }
    content = json.dumps(backup, indent=2, ensure_ascii=False)
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M%S")
    filename = f"ledgrab-backup-{timestamp}.json"
    return StreamingResponse(
        io.BytesIO(content.encode("utf-8")),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.post("/api/v1/system/restart", tags=["System"])
 def restart_server(_: AuthRequired):
    """Schedule a server restart and return immediately."""
    _schedule_restart()
    return {"status": "restarting"}
@router.post("/api/v1/system/restore", response_model=RestoreResponse, tags=["System"])
 async def restore_config(
    _: AuthRequired,
    file: UploadFile = File(...),
 ):
    """Upload a backup file to restore all configuration. Triggers server restart."""
    # Read and parse
    try:
        raw = await file.read()
        if len(raw) > 10 * 1024 * 1024:  # 10 MB limit
            raise HTTPException(status_code=400, detail="Backup file too large (max 10 MB)")
        backup = json.loads(raw)
    except json.JSONDecodeError as e:
        raise HTTPException(status_code=400, detail=f"Invalid JSON file: {e}")
    # Validate envelope
    meta = backup.get("meta")
    if not isinstance(meta, dict) or meta.get("format") != "ledgrab-backup":
        raise HTTPException(status_code=400, detail="Not a valid LED Grab backup file")
    fmt_version = meta.get("format_version", 0)
    if fmt_version > 1:
        raise HTTPException(
            status_code=400,
            detail=f"Backup format version {fmt_version} is not supported by this server version",
        )
    stores = backup.get("stores")
    if not isinstance(stores, dict):
        raise HTTPException(status_code=400, detail="Backup file missing 'stores' section")
    known_keys = set(STORE_MAP.keys())
    present_keys = known_keys & set(stores.keys())
    if not present_keys:
        raise HTTPException(status_code=400, detail="Backup contains no recognized store data")
    for key in present_keys:
        if not isinstance(stores[key], dict):
            raise HTTPException(status_code=400, detail=f"Store '{key}' in backup is not a valid JSON object")
    # Write store files atomically (in thread to avoid blocking event loop)
    config = get_config()
    def _write_stores():
        count = 0
        for store_key, config_attr in STORE_MAP.items():
            if store_key in stores:
                file_path = Path(getattr(config.storage, config_attr))
                atomic_write_json(file_path, stores[store_key])
                count += 1
                logger.info(f"Restored store: {store_key} -> {file_path}")
        return count
    written = await asyncio.to_thread(_write_stores)
    logger.info(f"Restore complete: {written}/{len(STORE_MAP)} stores written. Scheduling restart...")
    _schedule_restart()
    missing = known_keys - present_keys
    return RestoreResponse(
        status="restored",
        stores_written=written,
        stores_total=len(STORE_MAP),
        missing_stores=sorted(missing) if missing else [],
        restart_scheduled=True,
        message=f"Restored {written} stores. Server restarting...",
    )
 # ---------------------------------------------------------------------------
 # Auto-backup settings & saved backups
 # ---------------------------------------------------------------------------
@router.get(
    "/api/v1/system/auto-backup/settings",
    response_model=AutoBackupStatusResponse,
    tags=["System"],
 )
 async def get_auto_backup_settings(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Get auto-backup settings and status."""
    return engine.get_settings()
@router.put(
    "/api/v1/system/auto-backup/settings",
    response_model=AutoBackupStatusResponse,
    tags=["System"],
 )
 async def update_auto_backup_settings(
    _: AuthRequired,
    body: AutoBackupSettings,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Update auto-backup settings (enable/disable, interval, max backups)."""
    return await engine.update_settings(
        enabled=body.enabled,
        interval_hours=body.interval_hours,
        max_backups=body.max_backups,
    )
@router.post("/api/v1/system/auto-backup/trigger", tags=["System"])
 async def trigger_backup(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Manually trigger a backup now."""
    backup = await engine.trigger_backup()
    return {"status": "ok", "backup": backup}
@router.get(
    "/api/v1/system/backups",
    response_model=BackupListResponse,
    tags=["System"],
 )
 async def list_backups(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """List all saved backup files."""
    backups = engine.list_backups()
    return BackupListResponse(
        backups=[BackupFileInfo(**b) for b in backups],
        count=len(backups),
    )
@router.get("/api/v1/system/backups/{filename}", tags=["System"])
 def download_saved_backup(
    filename: str,
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Download a specific saved backup file."""
    try:
        path = engine.get_backup_path(filename)
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(status_code=404, detail=str(e))
    content = path.read_bytes()
    return StreamingResponse(
        io.BytesIO(content),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.delete("/api/v1/system/backups/{filename}", tags=["System"])
 async def delete_saved_backup(
    filename: str,
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Delete a specific saved backup file."""
    try:
        engine.delete_backup(filename)
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(status_code=404, detail=str(e))
    return {"status": "deleted", "filename": filename}
--- a/server/src/wled_controller/api/routes/color_strip_processing.py
+++ b/server/src/wled_controller/api/routes/color_strip_processing.py
@@ -2,10 +2,8 @@
 import asyncio
 import json as _json
 import time as _time
 import uuid as _uuid
 import numpy as np
 from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSocketDisconnect
 from wled_controller.api.auth import AuthRequired
--- a/server/src/wled_controller/api/routes/color_strip_sources.py
+++ b/server/src/wled_controller/api/routes/color_strip_sources.py
@@ -32,11 +32,10 @@ from wled_controller.api.schemas.devices import (
 )
 from wled_controller.core.capture.calibration import (
    calibration_from_dict,
    calibration_to_dict,
 )
 from wled_controller.core.capture.screen_capture import get_available_displays
 from wled_controller.core.processing.processor_manager import ProcessorManager
-from wled_controller.storage.color_strip_source import AdvancedPictureColorStripSource, ApiInputColorStripSource, CompositeColorStripSource, NotificationColorStripSource, PictureColorStripSource, ProcessedColorStripSource
+from wled_controller.storage.color_strip_source import AdvancedPictureColorStripSource, ApiInputColorStripSource, CompositeColorStripSource, NotificationColorStripSource, PictureColorStripSource
 from wled_controller.storage.color_strip_store import ColorStripStore
 from wled_controller.storage.picture_source import ProcessedPictureSource, ScreenCapturePictureSource
 from wled_controller.storage.picture_source_store import PictureSourceStore
@@ -136,7 +135,7 @@ def _extract_css_kwargs(data) -> dict:
    else:
        kwargs["calibration"] = None
    kwargs["stops"] = [s.model_dump() for s in data.stops] if data.stops is not None else None
-    kwargs["layers"] = [l.model_dump() for l in data.layers] if data.layers is not None else None
+    kwargs["layers"] = [layer.model_dump() for layer in data.layers] if data.layers is not None else None
    kwargs["zones"] = [z.model_dump() for z in data.zones] if data.zones is not None else None
    kwargs["animation"] = data.animation.model_dump() if data.animation else None
    return kwargs
@@ -870,7 +869,7 @@ async def test_color_strip_ws(
            meta["border_width"] = cal.border_width
        if is_composite and hasattr(source, "layers"):
            # Send layer info for composite preview
-            enabled_layers = [l for l in source.layers if l.get("enabled", True)]
+            enabled_layers = [layer for layer in source.layers if layer.get("enabled", True)]
            layer_infos = []  # [{name, id, is_notification, has_brightness, ...}, ...]
            for layer in enabled_layers:
                info = {"id": layer["source_id"], "name": layer.get("source_id", "?"),
@@ -890,6 +889,14 @@ async def test_color_strip_ws(
            meta["layer_infos"] = layer_infos
        await websocket.send_text(_json.dumps(meta))
        # For api_input: send the current buffer immediately so the client
        # gets a frame right away (fallback color if inactive) rather than
        # leaving the canvas blank/stale until external data arrives.
        if is_api_input:
            initial_colors = stream.get_latest_colors()
            if initial_colors is not None:
                await websocket.send_bytes(initial_colors.tobytes())
        # For picture sources, grab the live stream for frame preview
        _frame_live = None
        if is_picture and hasattr(stream, 'live_stream'):
--- a/server/src/wled_controller/api/routes/devices.py
+++ b/server/src/wled_controller/api/routes/devices.py
@@ -16,6 +16,7 @@ from wled_controller.api.dependencies import (
    get_processor_manager,
 )
 from wled_controller.api.schemas.devices import (
    BrightnessRequest,
    DeviceCreate,
    DeviceListResponse,
    DeviceResponse,
@@ -25,12 +26,12 @@ from wled_controller.api.schemas.devices import (
    DiscoverDevicesResponse,
    OpenRGBZoneResponse,
    OpenRGBZonesResponse,
    PowerRequest,
 )
 from wled_controller.core.processing.processor_manager import ProcessorManager
 from wled_controller.storage import DeviceStore
 from wled_controller.storage.output_target_store import OutputTargetStore
 from wled_controller.utils import get_logger
 from wled_controller.storage.base_store import EntityNotFoundError
 logger = get_logger(__name__)
@@ -53,18 +54,19 @@ def _device_to_response(device) -> DeviceResponse:
        zone_mode=device.zone_mode,
        capabilities=sorted(get_device_capabilities(device.device_type)),
        tags=device.tags,
-        dmx_protocol=getattr(device, 'dmx_protocol', 'artnet'),
+        dmx_protocol=device.dmx_protocol,
-        dmx_start_universe=getattr(device, 'dmx_start_universe', 0),
+        dmx_start_universe=device.dmx_start_universe,
-        dmx_start_channel=getattr(device, 'dmx_start_channel', 1),
+        dmx_start_channel=device.dmx_start_channel,
-        espnow_peer_mac=getattr(device, 'espnow_peer_mac', ''),
+        espnow_peer_mac=device.espnow_peer_mac,
-        espnow_channel=getattr(device, 'espnow_channel', 1),
+        espnow_channel=device.espnow_channel,
-        hue_username=getattr(device, 'hue_username', ''),
+        hue_username=device.hue_username,
-        hue_client_key=getattr(device, 'hue_client_key', ''),
+        hue_client_key=device.hue_client_key,
-        hue_entertainment_group_id=getattr(device, 'hue_entertainment_group_id', ''),
+        hue_entertainment_group_id=device.hue_entertainment_group_id,
-        spi_speed_hz=getattr(device, 'spi_speed_hz', 800000),
+        spi_speed_hz=device.spi_speed_hz,
-        spi_led_type=getattr(device, 'spi_led_type', 'WS2812B'),
+        spi_led_type=device.spi_led_type,
-        chroma_device_type=getattr(device, 'chroma_device_type', 'chromalink'),
+        chroma_device_type=device.chroma_device_type,
-        gamesense_device_type=getattr(device, 'gamesense_device_type', 'keyboard'),
+        gamesense_device_type=device.gamesense_device_type,
        default_css_processing_template_id=device.default_css_processing_template_id,
        created_at=device.created_at,
        updated_at=device.updated_at,
    )
@@ -508,7 +510,7 @@ async def get_device_brightness(
@router.put("/api/v1/devices/{device_id}/brightness", tags=["Settings"])
 async def set_device_brightness(
    device_id: str,
-    body: dict,
+    body: BrightnessRequest,
    _auth: AuthRequired,
    store: DeviceStore = Depends(get_device_store),
    manager: ProcessorManager = Depends(get_processor_manager),
@@ -521,9 +523,7 @@ async def set_device_brightness(
    if "brightness_control" not in get_device_capabilities(device.device_type):
        raise HTTPException(status_code=400, detail=f"Brightness control is not supported for {device.device_type} devices")
-    bri = body.get("brightness")
+    bri = body.brightness
    if bri is None or not isinstance(bri, int) or not 0 <= bri <= 255:
        raise HTTPException(status_code=400, detail="brightness must be an integer 0-255")
    try:
        try:
@@ -581,7 +581,7 @@ async def get_device_power(
@router.put("/api/v1/devices/{device_id}/power", tags=["Settings"])
 async def set_device_power(
    device_id: str,
-    body: dict,
+    body: PowerRequest,
    _auth: AuthRequired,
    store: DeviceStore = Depends(get_device_store),
    manager: ProcessorManager = Depends(get_processor_manager),
@@ -594,9 +594,7 @@ async def set_device_power(
    if "power_control" not in get_device_capabilities(device.device_type):
        raise HTTPException(status_code=400, detail=f"Power control is not supported for {device.device_type} devices")
-    on = body.get("on")
+    on = body.power
    if on is None or not isinstance(on, bool):
        raise HTTPException(status_code=400, detail="'on' must be a boolean")
    try:
        # For serial devices, use the cached idle client to avoid port conflicts
--- a/server/src/wled_controller/api/routes/output_targets.py
+++ b/server/src/wled_controller/api/routes/output_targets.py
@@ -1,57 +1,25 @@
-"""Output target routes: CRUD, processing control, settings, state, metrics."""
+"""Output target routes: CRUD endpoints and batch state/metrics queries."""
 import asyncio
 import base64
 import io
 import time
-import numpy as np
+from fastapi import APIRouter, HTTPException, Depends
 from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSocketDisconnect
 from PIL import Image
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import (
    fire_entity_event,
    get_color_strip_store,
    get_device_store,
    get_pattern_template_store,
    get_picture_source_store,
    get_output_target_store,
    get_pp_template_store,
    get_processor_manager,
    get_template_store,
 )
 from wled_controller.api.schemas.output_targets import (
    BulkTargetRequest,
    BulkTargetResponse,
    ExtractedColorResponse,
    KCTestRectangleResponse,
    KCTestResponse,
    KeyColorsResponse,
    KeyColorsSettingsSchema,
    OutputTargetCreate,
    OutputTargetListResponse,
    OutputTargetResponse,
    OutputTargetUpdate,
    TargetMetricsResponse,
    TargetProcessingState,
 )
 from wled_controller.core.capture_engines import EngineRegistry
 from wled_controller.core.filters import FilterRegistry, ImagePool
 from wled_controller.core.processing.processor_manager import ProcessorManager
 from wled_controller.core.capture.screen_capture import (
    calculate_average_color,
    calculate_dominant_color,
    calculate_median_color,
    get_available_displays,
 )
 from wled_controller.storage.color_strip_store import ColorStripStore
 from wled_controller.storage.color_strip_source import AdvancedPictureColorStripSource, PictureColorStripSource
 from wled_controller.storage import DeviceStore
 from wled_controller.storage.pattern_template_store import PatternTemplateStore
 from wled_controller.storage.picture_source import ScreenCapturePictureSource, StaticImagePictureSource
 from wled_controller.storage.picture_source_store import PictureSourceStore
 from wled_controller.storage.template_store import TemplateStore
 from wled_controller.storage.wled_output_target import WledOutputTarget
 from wled_controller.storage.key_colors_output_target import (
    KeyColorsSettings,
@@ -326,7 +294,7 @@ async def update_target(
        except ValueError:
            pass
-        # Device change requires async stop → swap → start cycle
+        # Device change requires async stop -> swap -> start cycle
        if data.device_id is not None:
            try:
                await manager.update_target_device(target_id, target.device_id)
@@ -377,795 +345,3 @@ async def delete_target(
    except Exception as e:
        logger.error(f"Failed to delete target: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 # ===== BULK PROCESSING CONTROL ENDPOINTS =====
@router.post("/api/v1/output-targets/bulk/start", response_model=BulkTargetResponse, tags=["Processing"])
 async def bulk_start_processing(
    body: BulkTargetRequest,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Start processing for multiple output targets. Returns lists of started IDs and per-ID errors."""
    started: list[str] = []
    errors: dict[str, str] = {}
    for target_id in body.ids:
        try:
            target_store.get_target(target_id)
            await manager.start_processing(target_id)
            started.append(target_id)
            logger.info(f"Bulk start: started processing for target {target_id}")
        except ValueError as e:
            errors[target_id] = str(e)
        except RuntimeError as e:
            msg = str(e)
            for t in target_store.get_all_targets():
                if t.id in msg:
                    msg = msg.replace(t.id, f"'{t.name}'")
            errors[target_id] = msg
        except Exception as e:
            logger.error(f"Bulk start: failed to start target {target_id}: {e}")
            errors[target_id] = str(e)
    return BulkTargetResponse(started=started, errors=errors)
@router.post("/api/v1/output-targets/bulk/stop", response_model=BulkTargetResponse, tags=["Processing"])
 async def bulk_stop_processing(
    body: BulkTargetRequest,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop processing for multiple output targets. Returns lists of stopped IDs and per-ID errors."""
    stopped: list[str] = []
    errors: dict[str, str] = {}
    for target_id in body.ids:
        try:
            await manager.stop_processing(target_id)
            stopped.append(target_id)
            logger.info(f"Bulk stop: stopped processing for target {target_id}")
        except ValueError as e:
            errors[target_id] = str(e)
        except Exception as e:
            logger.error(f"Bulk stop: failed to stop target {target_id}: {e}")
            errors[target_id] = str(e)
    return BulkTargetResponse(stopped=stopped, errors=errors)
 # ===== PROCESSING CONTROL ENDPOINTS =====
@router.post("/api/v1/output-targets/{target_id}/start", tags=["Processing"])
 async def start_processing(
    target_id: str,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Start processing for a output target."""
    try:
        # Verify target exists in store
        target_store.get_target(target_id)
        await manager.start_processing(target_id)
        logger.info(f"Started processing for target {target_id}")
        return {"status": "started", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except RuntimeError as e:
        # Resolve target IDs to human-readable names in error messages
        msg = str(e)
        for t in target_store.get_all_targets():
            if t.id in msg:
                msg = msg.replace(t.id, f"'{t.name}'")
        raise HTTPException(status_code=409, detail=msg)
    except Exception as e:
        logger.error(f"Failed to start processing: {e}")
        raise HTTPException(status_code=500, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/stop", tags=["Processing"])
 async def stop_processing(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop processing for a output target."""
    try:
        await manager.stop_processing(target_id)
        logger.info(f"Stopped processing for target {target_id}")
        return {"status": "stopped", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to stop processing: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 # ===== STATE & METRICS ENDPOINTS =====
@router.get("/api/v1/output-targets/{target_id}/state", response_model=TargetProcessingState, tags=["Processing"])
 async def get_target_state(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get current processing state for a target."""
    try:
        state = manager.get_target_state(target_id)
        return TargetProcessingState(**state)
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to get target state: {e}")
        raise HTTPException(status_code=500, detail=str(e))
@router.get("/api/v1/output-targets/{target_id}/metrics", response_model=TargetMetricsResponse, tags=["Metrics"])
 async def get_target_metrics(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get processing metrics for a target."""
    try:
        metrics = manager.get_target_metrics(target_id)
        return TargetMetricsResponse(**metrics)
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to get target metrics: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 # ===== KEY COLORS ENDPOINTS =====
@router.get("/api/v1/output-targets/{target_id}/colors", response_model=KeyColorsResponse, tags=["Key Colors"])
 async def get_target_colors(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get latest extracted colors for a key-colors target (polling)."""
    try:
        raw_colors = manager.get_kc_latest_colors(target_id)
        colors = {}
        for name, (r, g, b) in raw_colors.items():
            colors[name] = ExtractedColorResponse(
                r=r, g=g, b=b,
                hex=f"#{r:02x}{g:02x}{b:02x}",
            )
        from datetime import datetime, timezone
        return KeyColorsResponse(
            target_id=target_id,
            colors=colors,
            timestamp=datetime.now(timezone.utc),
        )
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/test", response_model=KCTestResponse, tags=["Key Colors"])
 async def test_kc_target(
    target_id: str,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    source_store: PictureSourceStore = Depends(get_picture_source_store),
    template_store: TemplateStore = Depends(get_template_store),
    pattern_store: PatternTemplateStore = Depends(get_pattern_template_store),
    processor_manager: ProcessorManager = Depends(get_processor_manager),
    device_store: DeviceStore = Depends(get_device_store),
    pp_template_store=Depends(get_pp_template_store),
 ):
    """Test a key-colors target: capture a frame, extract colors from each rectangle."""
    import httpx
    stream = None
    try:
        # 1. Load and validate KC target
        try:
            target = target_store.get_target(target_id)
        except ValueError as e:
            raise HTTPException(status_code=404, detail=str(e))
        if not isinstance(target, KeyColorsOutputTarget):
            raise HTTPException(status_code=400, detail="Target is not a key_colors target")
        settings = target.settings
        # 2. Resolve pattern template
        if not settings.pattern_template_id:
            raise HTTPException(status_code=400, detail="No pattern template configured")
        try:
            pattern_tmpl = pattern_store.get_template(settings.pattern_template_id)
        except ValueError:
            raise HTTPException(status_code=400, detail=f"Pattern template not found: {settings.pattern_template_id}")
        rectangles = pattern_tmpl.rectangles
        if not rectangles:
            raise HTTPException(status_code=400, detail="Pattern template has no rectangles")
        # 3. Resolve picture source and capture a frame
        if not target.picture_source_id:
            raise HTTPException(status_code=400, detail="No picture source configured")
        try:
            chain = source_store.resolve_stream_chain(target.picture_source_id)
        except EntityNotFoundError as e:
            raise HTTPException(status_code=404, detail=str(e))
        except ValueError as e:
            raise HTTPException(status_code=400, detail=str(e))
        raw_stream = chain["raw_stream"]
        if isinstance(raw_stream, StaticImagePictureSource):
            source = raw_stream.image_source
            if source.startswith(("http://", "https://")):
                async with httpx.AsyncClient(timeout=15, follow_redirects=True) as client:
                    resp = await client.get(source)
                    resp.raise_for_status()
                    pil_image = Image.open(io.BytesIO(resp.content)).convert("RGB")
            else:
                from pathlib import Path
                path = Path(source)
                if not path.exists():
                    raise HTTPException(status_code=400, detail=f"Image file not found: {source}")
                pil_image = Image.open(path).convert("RGB")
        elif isinstance(raw_stream, ScreenCapturePictureSource):
            try:
                capture_template = template_store.get_template(raw_stream.capture_template_id)
            except ValueError:
                raise HTTPException(
                    status_code=400,
                    detail=f"Capture template not found: {raw_stream.capture_template_id}",
                )
            display_index = raw_stream.display_index
            if capture_template.engine_type not in EngineRegistry.get_available_engines():
                raise HTTPException(
                    status_code=400,
                    detail=f"Engine '{capture_template.engine_type}' is not available on this system",
                )
            locked_device_id = processor_manager.get_display_lock_info(display_index)
            if locked_device_id:
                try:
                    device = device_store.get_device(locked_device_id)
                    device_name = device.name
                except Exception:
                    device_name = locked_device_id
                raise HTTPException(
                    status_code=409,
                    detail=f"Display {display_index} is currently being captured by device '{device_name}'. "
                           f"Please stop the device processing before testing.",
                )
            stream = EngineRegistry.create_stream(
                capture_template.engine_type, display_index, capture_template.engine_config
            )
            stream.initialize()
            screen_capture = stream.capture_frame()
            if screen_capture is None:
                raise RuntimeError("No frame captured")
            if isinstance(screen_capture.image, np.ndarray):
                pil_image = Image.fromarray(screen_capture.image)
            else:
                raise ValueError("Unexpected image format from engine")
        else:
            raise HTTPException(status_code=400, detail="Unsupported picture source type")
        # 3b. Apply postprocessing filters (if the picture source has a filter chain)
        pp_template_ids = chain.get("postprocessing_template_ids", [])
        if pp_template_ids and pp_template_store:
            img_array = np.array(pil_image)
            image_pool = ImagePool()
            for pp_id in pp_template_ids:
                try:
                    pp_template = pp_template_store.get_template(pp_id)
                except ValueError:
                    logger.warning(f"KC test: PP template {pp_id} not found, skipping")
                    continue
                flat_filters = pp_template_store.resolve_filter_instances(pp_template.filters)
                for fi in flat_filters:
                    try:
                        f = FilterRegistry.create_instance(fi.filter_id, fi.options)
                        result = f.process_image(img_array, image_pool)
                        if result is not None:
                            img_array = result
                    except ValueError:
                        logger.warning(f"KC test: unknown filter '{fi.filter_id}', skipping")
            pil_image = Image.fromarray(img_array)
        # 4. Extract colors from each rectangle
        img_array = np.array(pil_image)
        h, w = img_array.shape[:2]
        calc_fns = {
            "average": calculate_average_color,
            "median": calculate_median_color,
            "dominant": calculate_dominant_color,
        }
        calc_fn = calc_fns.get(settings.interpolation_mode, calculate_average_color)
        result_rects = []
        for rect in rectangles:
            px_x = max(0, int(rect.x * w))
            px_y = max(0, int(rect.y * h))
            px_w = max(1, int(rect.width * w))
            px_h = max(1, int(rect.height * h))
            px_x = min(px_x, w - 1)
            px_y = min(px_y, h - 1)
            px_w = min(px_w, w - px_x)
            px_h = min(px_h, h - px_y)
            sub_img = img_array[px_y:px_y + px_h, px_x:px_x + px_w]
            r, g, b = calc_fn(sub_img)
            result_rects.append(KCTestRectangleResponse(
                name=rect.name,
                x=rect.x,
                y=rect.y,
                width=rect.width,
                height=rect.height,
                color=ExtractedColorResponse(r=r, g=g, b=b, hex=f"#{r:02x}{g:02x}{b:02x}"),
            ))
        # 5. Encode frame as base64 JPEG
        full_buffer = io.BytesIO()
        pil_image.save(full_buffer, format='JPEG', quality=90)
        full_buffer.seek(0)
        full_b64 = base64.b64encode(full_buffer.getvalue()).decode('utf-8')
        image_data_uri = f"data:image/jpeg;base64,{full_b64}"
        return KCTestResponse(
            image=image_data_uri,
            rectangles=result_rects,
            interpolation_mode=settings.interpolation_mode,
            pattern_template_name=pattern_tmpl.name,
        )
    except HTTPException:
        raise
    except EntityNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except RuntimeError as e:
        raise HTTPException(status_code=500, detail=f"Capture error: {str(e)}")
    except Exception as e:
        logger.error(f"Failed to test KC target: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
    finally:
        if stream:
            try:
                stream.cleanup()
            except Exception as e:
                logger.error(f"Error cleaning up test stream: {e}")
@router.websocket("/api/v1/output-targets/{target_id}/test/ws")
 async def test_kc_target_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
    fps: int = Query(3),
    preview_width: int = Query(480),
 ):
    """WebSocket for real-time KC target test preview. Auth via ?token=<api_key>.
    Streams JSON frames: {"type": "frame", "image": "data:image/jpeg;base64,...",
    "rectangles": [...], "pattern_template_name": "...", "interpolation_mode": "..."}
    """
    import json as _json
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    # Load stores
    target_store_inst: OutputTargetStore = get_output_target_store()
    source_store_inst: PictureSourceStore = get_picture_source_store()
    template_store_inst: TemplateStore = get_template_store()
    pattern_store_inst: PatternTemplateStore = get_pattern_template_store()
    processor_manager_inst: ProcessorManager = get_processor_manager()
    device_store_inst: DeviceStore = get_device_store()
    pp_template_store_inst = get_pp_template_store()
    # Validate target
    try:
        target = target_store_inst.get_target(target_id)
    except ValueError as e:
        await websocket.close(code=4004, reason=str(e))
        return
    if not isinstance(target, KeyColorsOutputTarget):
        await websocket.close(code=4003, reason="Target is not a key_colors target")
        return
    settings = target.settings
    if not settings.pattern_template_id:
        await websocket.close(code=4003, reason="No pattern template configured")
        return
    try:
        pattern_tmpl = pattern_store_inst.get_template(settings.pattern_template_id)
    except ValueError:
        await websocket.close(code=4003, reason=f"Pattern template not found: {settings.pattern_template_id}")
        return
    rectangles = pattern_tmpl.rectangles
    if not rectangles:
        await websocket.close(code=4003, reason="Pattern template has no rectangles")
        return
    if not target.picture_source_id:
        await websocket.close(code=4003, reason="No picture source configured")
        return
    try:
        chain = source_store_inst.resolve_stream_chain(target.picture_source_id)
    except ValueError as e:
        await websocket.close(code=4003, reason=str(e))
        return
    raw_stream = chain["raw_stream"]
    # For screen capture sources, check display lock
    if isinstance(raw_stream, ScreenCapturePictureSource):
        display_index = raw_stream.display_index
        locked_device_id = processor_manager_inst.get_display_lock_info(display_index)
        if locked_device_id:
            try:
                device = device_store_inst.get_device(locked_device_id)
                device_name = device.name
            except Exception:
                device_name = locked_device_id
            await websocket.close(
                code=4003,
                reason=f"Display {display_index} is captured by '{device_name}'. Stop processing first.",
            )
            return
    fps = max(1, min(30, fps))
    preview_width = max(120, min(1920, preview_width))
    frame_interval = 1.0 / fps
    calc_fns = {
        "average": calculate_average_color,
        "median": calculate_median_color,
        "dominant": calculate_dominant_color,
    }
    calc_fn = calc_fns.get(settings.interpolation_mode, calculate_average_color)
    await websocket.accept()
    logger.info(f"KC test WS connected for {target_id} (fps={fps})")
    # Use the shared LiveStreamManager so we share the capture stream with
    # running LED targets instead of creating a competing DXGI duplicator.
    live_stream_mgr = processor_manager_inst._live_stream_manager
    live_stream = None
    try:
        live_stream = await asyncio.to_thread(
            live_stream_mgr.acquire, target.picture_source_id
        )
        logger.info(f"KC test WS acquired shared live stream for {target.picture_source_id}")
        prev_frame_ref = None
        while True:
            loop_start = time.monotonic()
            try:
                capture = await asyncio.to_thread(live_stream.get_latest_frame)
                if capture is None or capture.image is None:
                    await asyncio.sleep(frame_interval)
                    continue
                # Skip if same frame object (no new capture yet)
                if capture is prev_frame_ref:
                    await asyncio.sleep(frame_interval * 0.5)
                    continue
                prev_frame_ref = capture
                pil_image = Image.fromarray(capture.image) if isinstance(capture.image, np.ndarray) else None
                if pil_image is None:
                    await asyncio.sleep(frame_interval)
                    continue
                # Apply postprocessing (if the source chain has PP templates)
                chain = source_store_inst.resolve_stream_chain(target.picture_source_id)
                pp_template_ids = chain.get("postprocessing_template_ids", [])
                if pp_template_ids and pp_template_store_inst:
                    img_array = np.array(pil_image)
                    image_pool = ImagePool()
                    for pp_id in pp_template_ids:
                        try:
                            pp_template = pp_template_store_inst.get_template(pp_id)
                        except ValueError:
                            continue
                        flat_filters = pp_template_store_inst.resolve_filter_instances(pp_template.filters)
                        for fi in flat_filters:
                            try:
                                f = FilterRegistry.create_instance(fi.filter_id, fi.options)
                                result = f.process_image(img_array, image_pool)
                                if result is not None:
                                    img_array = result
                            except ValueError:
                                pass
                        pil_image = Image.fromarray(img_array)
                # Extract colors
                img_array = np.array(pil_image)
                h, w = img_array.shape[:2]
                result_rects = []
                for rect in rectangles:
                    px_x = max(0, int(rect.x * w))
                    px_y = max(0, int(rect.y * h))
                    px_w = max(1, int(rect.width * w))
                    px_h = max(1, int(rect.height * h))
                    px_x = min(px_x, w - 1)
                    px_y = min(px_y, h - 1)
                    px_w = min(px_w, w - px_x)
                    px_h = min(px_h, h - px_y)
                    sub_img = img_array[px_y:px_y + px_h, px_x:px_x + px_w]
                    r, g, b = calc_fn(sub_img)
                    result_rects.append({
                        "name": rect.name,
                        "x": rect.x,
                        "y": rect.y,
                        "width": rect.width,
                        "height": rect.height,
                        "color": {"r": r, "g": g, "b": b, "hex": f"#{r:02x}{g:02x}{b:02x}"},
                    })
                # Encode frame as JPEG
                if preview_width and pil_image.width > preview_width:
                    ratio = preview_width / pil_image.width
                    thumb = pil_image.resize((preview_width, int(pil_image.height * ratio)), Image.LANCZOS)
                else:
                    thumb = pil_image
                buf = io.BytesIO()
                thumb.save(buf, format="JPEG", quality=85)
                b64 = base64.b64encode(buf.getvalue()).decode()
                await websocket.send_text(_json.dumps({
                    "type": "frame",
                    "image": f"data:image/jpeg;base64,{b64}",
                    "rectangles": result_rects,
                    "pattern_template_name": pattern_tmpl.name,
                    "interpolation_mode": settings.interpolation_mode,
                }))
            except (WebSocketDisconnect, Exception) as inner_e:
                if isinstance(inner_e, WebSocketDisconnect):
                    raise
                logger.warning(f"KC test WS frame error for {target_id}: {inner_e}")
            elapsed = time.monotonic() - loop_start
            sleep_time = frame_interval - elapsed
            if sleep_time > 0:
                await asyncio.sleep(sleep_time)
    except WebSocketDisconnect:
        logger.info(f"KC test WS disconnected for {target_id}")
    except Exception as e:
        logger.error(f"KC test WS error for {target_id}: {e}", exc_info=True)
    finally:
        if live_stream is not None:
            try:
                await asyncio.to_thread(
                    live_stream_mgr.release, target.picture_source_id
                )
            except Exception:
                pass
        logger.info(f"KC test WS closed for {target_id}")
@router.websocket("/api/v1/output-targets/{target_id}/ws")
 async def target_colors_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
 ):
    """WebSocket for real-time key color updates. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    try:
        manager.add_kc_ws_client(target_id, websocket)
    except ValueError:
        await websocket.close(code=4004, reason="Target not found")
        return
    try:
        while True:
            # Keep alive — wait for client messages (or disconnect)
            await websocket.receive_text()
    except WebSocketDisconnect:
        pass
    finally:
        manager.remove_kc_ws_client(target_id, websocket)
@router.websocket("/api/v1/output-targets/{target_id}/led-preview/ws")
 async def led_preview_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
 ):
    """WebSocket for real-time LED strip preview. Sends binary RGB frames. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    try:
        manager.add_led_preview_client(target_id, websocket)
    except ValueError:
        await websocket.close(code=4004, reason="Target not found")
        return
    try:
        while True:
            await websocket.receive_text()
    except WebSocketDisconnect:
        pass
    finally:
        manager.remove_led_preview_client(target_id, websocket)
 # ===== STATE CHANGE EVENT STREAM =====
@router.websocket("/api/v1/events/ws")
 async def events_ws(
    websocket: WebSocket,
    token: str = Query(""),
 ):
    """WebSocket for real-time state change events. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    queue = manager.subscribe_events()
    try:
        while True:
            event = await queue.get()
            await websocket.send_json(event)
    except WebSocketDisconnect:
        pass
    except Exception:
        pass
    finally:
        manager.unsubscribe_events(queue)
 # ===== OVERLAY VISUALIZATION =====
@router.post("/api/v1/output-targets/{target_id}/overlay/start", tags=["Visualization"])
 async def start_target_overlay(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
    target_store: OutputTargetStore = Depends(get_output_target_store),
    color_strip_store: ColorStripStore = Depends(get_color_strip_store),
    picture_source_store: PictureSourceStore = Depends(get_picture_source_store),
 ):
    """Start screen overlay visualization for a target.
    Displays a transparent overlay on the target display showing:
    - Border sampling zones (colored rectangles)
    - LED position markers (numbered dots)
    - Pixel-to-LED mapping ranges (colored segments)
    - Calibration info text
    """
    try:
        # Get target name from store
        target = target_store.get_target(target_id)
        if not target:
            raise ValueError(f"Target {target_id} not found")
        # Pre-load calibration and display info from the CSS store so the overlay
        # can start even when processing is not currently running.
        calibration = None
        display_info = None
        if isinstance(target, WledOutputTarget) and target.color_strip_source_id:
            first_css_id = target.color_strip_source_id
            if first_css_id:
                try:
                    css = color_strip_store.get_source(first_css_id)
                    if isinstance(css, (PictureColorStripSource, AdvancedPictureColorStripSource)) and css.calibration:
                        calibration = css.calibration
                        # Resolve the display this CSS is capturing
                        from wled_controller.api.routes.color_strip_sources import _resolve_display_index
                        ps_id = getattr(css, "picture_source_id", "") or ""
                        display_index = _resolve_display_index(ps_id, picture_source_store)
                        displays = get_available_displays()
                        if displays:
                            display_index = min(display_index, len(displays) - 1)
                            display_info = displays[display_index]
                except Exception as e:
                    logger.warning(f"Could not pre-load CSS calibration for overlay on {target_id}: {e}")
        await manager.start_overlay(target_id, target.name, calibration=calibration, display_info=display_info)
        return {"status": "started", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except RuntimeError as e:
        raise HTTPException(status_code=409, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to start overlay: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/overlay/stop", tags=["Visualization"])
 async def stop_target_overlay(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop screen overlay visualization for a target."""
    try:
        await manager.stop_overlay(target_id)
        return {"status": "stopped", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to stop overlay: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
@router.get("/api/v1/output-targets/{target_id}/overlay/status", tags=["Visualization"])
 async def get_overlay_status(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Check if overlay is active for a target."""
    try:
        active = manager.is_overlay_active(target_id)
        return {"target_id": target_id, "active": active}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
--- a/server/src/wled_controller/api/routes/output_targets_control.py
+++ b/server/src/wled_controller/api/routes/output_targets_control.py
@@ -0,0 +1,338 @@
 """Output target routes: processing control, state, metrics, events, overlay.
 Extracted from output_targets.py to keep files under 800 lines.
 """
 from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSocketDisconnect
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import (
    get_color_strip_store,
    get_output_target_store,
    get_picture_source_store,
    get_processor_manager,
 )
 from wled_controller.api.schemas.output_targets import (
    BulkTargetRequest,
    BulkTargetResponse,
    TargetMetricsResponse,
    TargetProcessingState,
 )
 from wled_controller.core.processing.processor_manager import ProcessorManager
 from wled_controller.core.capture.screen_capture import get_available_displays
 from wled_controller.storage.color_strip_store import ColorStripStore
 from wled_controller.storage.color_strip_source import AdvancedPictureColorStripSource, PictureColorStripSource
 from wled_controller.storage.picture_source_store import PictureSourceStore
 from wled_controller.storage.wled_output_target import WledOutputTarget
 from wled_controller.storage.output_target_store import OutputTargetStore
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 router = APIRouter()
 # ===== BULK PROCESSING CONTROL ENDPOINTS =====
@router.post("/api/v1/output-targets/bulk/start", response_model=BulkTargetResponse, tags=["Processing"])
 async def bulk_start_processing(
    body: BulkTargetRequest,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Start processing for multiple output targets. Returns lists of started IDs and per-ID errors."""
    started: list[str] = []
    errors: dict[str, str] = {}
    for target_id in body.ids:
        try:
            target_store.get_target(target_id)
            await manager.start_processing(target_id)
            started.append(target_id)
            logger.info(f"Bulk start: started processing for target {target_id}")
        except ValueError as e:
            errors[target_id] = str(e)
        except RuntimeError as e:
            msg = str(e)
            for t in target_store.get_all_targets():
                if t.id in msg:
                    msg = msg.replace(t.id, f"'{t.name}'")
            errors[target_id] = msg
        except Exception as e:
            logger.error(f"Bulk start: failed to start target {target_id}: {e}")
            errors[target_id] = str(e)
    return BulkTargetResponse(started=started, errors=errors)
@router.post("/api/v1/output-targets/bulk/stop", response_model=BulkTargetResponse, tags=["Processing"])
 async def bulk_stop_processing(
    body: BulkTargetRequest,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop processing for multiple output targets. Returns lists of stopped IDs and per-ID errors."""
    stopped: list[str] = []
    errors: dict[str, str] = {}
    for target_id in body.ids:
        try:
            await manager.stop_processing(target_id)
            stopped.append(target_id)
            logger.info(f"Bulk stop: stopped processing for target {target_id}")
        except ValueError as e:
            errors[target_id] = str(e)
        except Exception as e:
            logger.error(f"Bulk stop: failed to stop target {target_id}: {e}")
            errors[target_id] = str(e)
    return BulkTargetResponse(stopped=stopped, errors=errors)
 # ===== PROCESSING CONTROL ENDPOINTS =====
@router.post("/api/v1/output-targets/{target_id}/start", tags=["Processing"])
 async def start_processing(
    target_id: str,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Start processing for a output target."""
    try:
        # Verify target exists in store
        target_store.get_target(target_id)
        await manager.start_processing(target_id)
        logger.info(f"Started processing for target {target_id}")
        return {"status": "started", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except RuntimeError as e:
        # Resolve target IDs to human-readable names in error messages
        msg = str(e)
        for t in target_store.get_all_targets():
            if t.id in msg:
                msg = msg.replace(t.id, f"'{t.name}'")
        raise HTTPException(status_code=409, detail=msg)
    except Exception as e:
        logger.error(f"Failed to start processing: {e}")
        raise HTTPException(status_code=500, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/stop", tags=["Processing"])
 async def stop_processing(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop processing for a output target."""
    try:
        await manager.stop_processing(target_id)
        logger.info(f"Stopped processing for target {target_id}")
        return {"status": "stopped", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to stop processing: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 # ===== STATE & METRICS ENDPOINTS =====
@router.get("/api/v1/output-targets/{target_id}/state", response_model=TargetProcessingState, tags=["Processing"])
 async def get_target_state(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get current processing state for a target."""
    try:
        state = manager.get_target_state(target_id)
        return TargetProcessingState(**state)
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to get target state: {e}")
        raise HTTPException(status_code=500, detail=str(e))
@router.get("/api/v1/output-targets/{target_id}/metrics", response_model=TargetMetricsResponse, tags=["Metrics"])
 async def get_target_metrics(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get processing metrics for a target."""
    try:
        metrics = manager.get_target_metrics(target_id)
        return TargetMetricsResponse(**metrics)
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to get target metrics: {e}")
        raise HTTPException(status_code=500, detail=str(e))
 # ===== STATE CHANGE EVENT STREAM =====
@router.websocket("/api/v1/events/ws")
 async def events_ws(
    websocket: WebSocket,
    token: str = Query(""),
 ):
    """WebSocket for real-time state change events. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    queue = manager.subscribe_events()
    try:
        while True:
            event = await queue.get()
            await websocket.send_json(event)
    except WebSocketDisconnect:
        pass
    except Exception:
        pass
    finally:
        manager.unsubscribe_events(queue)
 # ===== OVERLAY VISUALIZATION =====
@router.post("/api/v1/output-targets/{target_id}/overlay/start", tags=["Visualization"])
 async def start_target_overlay(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
    target_store: OutputTargetStore = Depends(get_output_target_store),
    color_strip_store: ColorStripStore = Depends(get_color_strip_store),
    picture_source_store: PictureSourceStore = Depends(get_picture_source_store),
 ):
    """Start screen overlay visualization for a target.
    Displays a transparent overlay on the target display showing:
    - Border sampling zones (colored rectangles)
    - LED position markers (numbered dots)
    - Pixel-to-LED mapping ranges (colored segments)
    - Calibration info text
    """
    try:
        # Get target name from store
        target = target_store.get_target(target_id)
        if not target:
            raise ValueError(f"Target {target_id} not found")
        # Pre-load calibration and display info from the CSS store so the overlay
        # can start even when processing is not currently running.
        calibration = None
        display_info = None
        if isinstance(target, WledOutputTarget) and target.color_strip_source_id:
            first_css_id = target.color_strip_source_id
            if first_css_id:
                try:
                    css = color_strip_store.get_source(first_css_id)
                    if isinstance(css, (PictureColorStripSource, AdvancedPictureColorStripSource)) and css.calibration:
                        calibration = css.calibration
                        # Resolve the display this CSS is capturing
                        from wled_controller.api.routes.color_strip_sources import _resolve_display_index
                        ps_id = getattr(css, "picture_source_id", "") or ""
                        display_index = _resolve_display_index(ps_id, picture_source_store)
                        displays = get_available_displays()
                        if displays:
                            display_index = min(display_index, len(displays) - 1)
                            display_info = displays[display_index]
                except Exception as e:
                    logger.warning(f"Could not pre-load CSS calibration for overlay on {target_id}: {e}")
        await manager.start_overlay(target_id, target.name, calibration=calibration, display_info=display_info)
        return {"status": "started", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except RuntimeError as e:
        raise HTTPException(status_code=409, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to start overlay: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/overlay/stop", tags=["Visualization"])
 async def stop_target_overlay(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Stop screen overlay visualization for a target."""
    try:
        await manager.stop_overlay(target_id)
        return {"status": "stopped", "target_id": target_id}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except Exception as e:
        logger.error(f"Failed to stop overlay: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
@router.get("/api/v1/output-targets/{target_id}/overlay/status", tags=["Visualization"])
 async def get_overlay_status(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Check if overlay is active for a target."""
    try:
        active = manager.is_overlay_active(target_id)
        return {"target_id": target_id, "active": active}
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
 # ===== LED PREVIEW WEBSOCKET =====
@router.websocket("/api/v1/output-targets/{target_id}/led-preview/ws")
 async def led_preview_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
 ):
    """WebSocket for real-time LED strip preview. Sends binary RGB frames. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    try:
        manager.add_led_preview_client(target_id, websocket)
    except ValueError:
        await websocket.close(code=4004, reason="Target not found")
        return
    try:
        while True:
            await websocket.receive_text()
    except WebSocketDisconnect:
        pass
    finally:
        manager.remove_led_preview_client(target_id, websocket)
--- a/server/src/wled_controller/api/routes/output_targets_keycolors.py
+++ b/server/src/wled_controller/api/routes/output_targets_keycolors.py
@@ -0,0 +1,540 @@
 """Output target routes: key colors endpoints, testing, and WebSocket streams.
 Extracted from output_targets.py to keep files under 800 lines.
 """
 import asyncio
 import base64
 import io
 import time
 import numpy as np
 from fastapi import APIRouter, HTTPException, Depends, Query, WebSocket, WebSocketDisconnect
 from PIL import Image
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import (
    get_device_store,
    get_output_target_store,
    get_pattern_template_store,
    get_picture_source_store,
    get_pp_template_store,
    get_processor_manager,
    get_template_store,
 )
 from wled_controller.api.schemas.output_targets import (
    ExtractedColorResponse,
    KCTestRectangleResponse,
    KCTestResponse,
    KeyColorsResponse,
 )
 from wled_controller.core.capture_engines import EngineRegistry
 from wled_controller.core.filters import FilterRegistry, ImagePool
 from wled_controller.core.processing.processor_manager import ProcessorManager
 from wled_controller.core.capture.screen_capture import (
    calculate_average_color,
    calculate_dominant_color,
    calculate_median_color,
 )
 from wled_controller.storage import DeviceStore
 from wled_controller.storage.pattern_template_store import PatternTemplateStore
 from wled_controller.storage.picture_source import ScreenCapturePictureSource, StaticImagePictureSource
 from wled_controller.storage.picture_source_store import PictureSourceStore
 from wled_controller.storage.template_store import TemplateStore
 from wled_controller.storage.key_colors_output_target import KeyColorsOutputTarget
 from wled_controller.storage.output_target_store import OutputTargetStore
 from wled_controller.storage.base_store import EntityNotFoundError
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 router = APIRouter()
 # ===== KEY COLORS ENDPOINTS =====
@router.get("/api/v1/output-targets/{target_id}/colors", response_model=KeyColorsResponse, tags=["Key Colors"])
 async def get_target_colors(
    target_id: str,
    _auth: AuthRequired,
    manager: ProcessorManager = Depends(get_processor_manager),
 ):
    """Get latest extracted colors for a key-colors target (polling)."""
    try:
        raw_colors = manager.get_kc_latest_colors(target_id)
        colors = {}
        for name, (r, g, b) in raw_colors.items():
            colors[name] = ExtractedColorResponse(
                r=r, g=g, b=b,
                hex=f"#{r:02x}{g:02x}{b:02x}",
            )
        from datetime import datetime, timezone
        return KeyColorsResponse(
            target_id=target_id,
            colors=colors,
            timestamp=datetime.now(timezone.utc),
        )
    except ValueError as e:
        raise HTTPException(status_code=404, detail=str(e))
@router.post("/api/v1/output-targets/{target_id}/test", response_model=KCTestResponse, tags=["Key Colors"])
 async def test_kc_target(
    target_id: str,
    _auth: AuthRequired,
    target_store: OutputTargetStore = Depends(get_output_target_store),
    source_store: PictureSourceStore = Depends(get_picture_source_store),
    template_store: TemplateStore = Depends(get_template_store),
    pattern_store: PatternTemplateStore = Depends(get_pattern_template_store),
    processor_manager: ProcessorManager = Depends(get_processor_manager),
    device_store: DeviceStore = Depends(get_device_store),
    pp_template_store=Depends(get_pp_template_store),
 ):
    """Test a key-colors target: capture a frame, extract colors from each rectangle."""
    import httpx
    stream = None
    try:
        # 1. Load and validate KC target
        try:
            target = target_store.get_target(target_id)
        except ValueError as e:
            raise HTTPException(status_code=404, detail=str(e))
        if not isinstance(target, KeyColorsOutputTarget):
            raise HTTPException(status_code=400, detail="Target is not a key_colors target")
        settings = target.settings
        # 2. Resolve pattern template
        if not settings.pattern_template_id:
            raise HTTPException(status_code=400, detail="No pattern template configured")
        try:
            pattern_tmpl = pattern_store.get_template(settings.pattern_template_id)
        except ValueError:
            raise HTTPException(status_code=400, detail=f"Pattern template not found: {settings.pattern_template_id}")
        rectangles = pattern_tmpl.rectangles
        if not rectangles:
            raise HTTPException(status_code=400, detail="Pattern template has no rectangles")
        # 3. Resolve picture source and capture a frame
        if not target.picture_source_id:
            raise HTTPException(status_code=400, detail="No picture source configured")
        try:
            chain = source_store.resolve_stream_chain(target.picture_source_id)
        except EntityNotFoundError as e:
            raise HTTPException(status_code=404, detail=str(e))
        except ValueError as e:
            raise HTTPException(status_code=400, detail=str(e))
        raw_stream = chain["raw_stream"]
        if isinstance(raw_stream, StaticImagePictureSource):
            source = raw_stream.image_source
            if source.startswith(("http://", "https://")):
                async with httpx.AsyncClient(timeout=15, follow_redirects=True) as client:
                    resp = await client.get(source)
                    resp.raise_for_status()
                    pil_image = Image.open(io.BytesIO(resp.content)).convert("RGB")
            else:
                from pathlib import Path
                path = Path(source)
                if not path.exists():
                    raise HTTPException(status_code=400, detail=f"Image file not found: {source}")
                pil_image = Image.open(path).convert("RGB")
        elif isinstance(raw_stream, ScreenCapturePictureSource):
            try:
                capture_template = template_store.get_template(raw_stream.capture_template_id)
            except ValueError:
                raise HTTPException(
                    status_code=400,
                    detail=f"Capture template not found: {raw_stream.capture_template_id}",
                )
            display_index = raw_stream.display_index
            if capture_template.engine_type not in EngineRegistry.get_available_engines():
                raise HTTPException(
                    status_code=400,
                    detail=f"Engine '{capture_template.engine_type}' is not available on this system",
                )
            locked_device_id = processor_manager.get_display_lock_info(display_index)
            if locked_device_id:
                try:
                    device = device_store.get_device(locked_device_id)
                    device_name = device.name
                except Exception:
                    device_name = locked_device_id
                raise HTTPException(
                    status_code=409,
                    detail=f"Display {display_index} is currently being captured by device '{device_name}'. "
                           f"Please stop the device processing before testing.",
                )
            stream = EngineRegistry.create_stream(
                capture_template.engine_type, display_index, capture_template.engine_config
            )
            stream.initialize()
            screen_capture = stream.capture_frame()
            if screen_capture is None:
                raise RuntimeError("No frame captured")
            if isinstance(screen_capture.image, np.ndarray):
                pil_image = Image.fromarray(screen_capture.image)
            else:
                raise ValueError("Unexpected image format from engine")
        else:
            raise HTTPException(status_code=400, detail="Unsupported picture source type")
        # 3b. Apply postprocessing filters (if the picture source has a filter chain)
        pp_template_ids = chain.get("postprocessing_template_ids", [])
        if pp_template_ids and pp_template_store:
            img_array = np.array(pil_image)
            image_pool = ImagePool()
            for pp_id in pp_template_ids:
                try:
                    pp_template = pp_template_store.get_template(pp_id)
                except ValueError:
                    logger.warning(f"KC test: PP template {pp_id} not found, skipping")
                    continue
                flat_filters = pp_template_store.resolve_filter_instances(pp_template.filters)
                for fi in flat_filters:
                    try:
                        f = FilterRegistry.create_instance(fi.filter_id, fi.options)
                        result = f.process_image(img_array, image_pool)
                        if result is not None:
                            img_array = result
                    except ValueError:
                        logger.warning(f"KC test: unknown filter '{fi.filter_id}', skipping")
            pil_image = Image.fromarray(img_array)
        # 4. Extract colors from each rectangle
        img_array = np.array(pil_image)
        h, w = img_array.shape[:2]
        calc_fns = {
            "average": calculate_average_color,
            "median": calculate_median_color,
            "dominant": calculate_dominant_color,
        }
        calc_fn = calc_fns.get(settings.interpolation_mode, calculate_average_color)
        result_rects = []
        for rect in rectangles:
            px_x = max(0, int(rect.x * w))
            px_y = max(0, int(rect.y * h))
            px_w = max(1, int(rect.width * w))
            px_h = max(1, int(rect.height * h))
            px_x = min(px_x, w - 1)
            px_y = min(px_y, h - 1)
            px_w = min(px_w, w - px_x)
            px_h = min(px_h, h - px_y)
            sub_img = img_array[px_y:px_y + px_h, px_x:px_x + px_w]
            r, g, b = calc_fn(sub_img)
            result_rects.append(KCTestRectangleResponse(
                name=rect.name,
                x=rect.x,
                y=rect.y,
                width=rect.width,
                height=rect.height,
                color=ExtractedColorResponse(r=r, g=g, b=b, hex=f"#{r:02x}{g:02x}{b:02x}"),
            ))
        # 5. Encode frame as base64 JPEG
        full_buffer = io.BytesIO()
        pil_image.save(full_buffer, format='JPEG', quality=90)
        full_buffer.seek(0)
        full_b64 = base64.b64encode(full_buffer.getvalue()).decode('utf-8')
        image_data_uri = f"data:image/jpeg;base64,{full_b64}"
        return KCTestResponse(
            image=image_data_uri,
            rectangles=result_rects,
            interpolation_mode=settings.interpolation_mode,
            pattern_template_name=pattern_tmpl.name,
        )
    except HTTPException:
        raise
    except EntityNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except RuntimeError as e:
        raise HTTPException(status_code=500, detail=f"Capture error: {str(e)}")
    except Exception as e:
        logger.error(f"Failed to test KC target: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))
    finally:
        if stream:
            try:
                stream.cleanup()
            except Exception as e:
                logger.error(f"Error cleaning up test stream: {e}")
@router.websocket("/api/v1/output-targets/{target_id}/test/ws")
 async def test_kc_target_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
    fps: int = Query(3),
    preview_width: int = Query(480),
 ):
    """WebSocket for real-time KC target test preview. Auth via ?token=<api_key>.
    Streams JSON frames: {"type": "frame", "image": "data:image/jpeg;base64,...",
    "rectangles": [...], "pattern_template_name": "...", "interpolation_mode": "..."}
    """
    import json as _json
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    # Load stores
    target_store_inst: OutputTargetStore = get_output_target_store()
    source_store_inst: PictureSourceStore = get_picture_source_store()
    get_template_store()
    pattern_store_inst: PatternTemplateStore = get_pattern_template_store()
    processor_manager_inst: ProcessorManager = get_processor_manager()
    device_store_inst: DeviceStore = get_device_store()
    pp_template_store_inst = get_pp_template_store()
    # Validate target
    try:
        target = target_store_inst.get_target(target_id)
    except ValueError as e:
        await websocket.close(code=4004, reason=str(e))
        return
    if not isinstance(target, KeyColorsOutputTarget):
        await websocket.close(code=4003, reason="Target is not a key_colors target")
        return
    settings = target.settings
    if not settings.pattern_template_id:
        await websocket.close(code=4003, reason="No pattern template configured")
        return
    try:
        pattern_tmpl = pattern_store_inst.get_template(settings.pattern_template_id)
    except ValueError:
        await websocket.close(code=4003, reason=f"Pattern template not found: {settings.pattern_template_id}")
        return
    rectangles = pattern_tmpl.rectangles
    if not rectangles:
        await websocket.close(code=4003, reason="Pattern template has no rectangles")
        return
    if not target.picture_source_id:
        await websocket.close(code=4003, reason="No picture source configured")
        return
    try:
        chain = source_store_inst.resolve_stream_chain(target.picture_source_id)
    except ValueError as e:
        await websocket.close(code=4003, reason=str(e))
        return
    raw_stream = chain["raw_stream"]
    # For screen capture sources, check display lock
    if isinstance(raw_stream, ScreenCapturePictureSource):
        display_index = raw_stream.display_index
        locked_device_id = processor_manager_inst.get_display_lock_info(display_index)
        if locked_device_id:
            try:
                device = device_store_inst.get_device(locked_device_id)
                device_name = device.name
            except Exception:
                device_name = locked_device_id
            await websocket.close(
                code=4003,
                reason=f"Display {display_index} is captured by '{device_name}'. Stop processing first.",
            )
            return
    fps = max(1, min(30, fps))
    preview_width = max(120, min(1920, preview_width))
    frame_interval = 1.0 / fps
    calc_fns = {
        "average": calculate_average_color,
        "median": calculate_median_color,
        "dominant": calculate_dominant_color,
    }
    calc_fn = calc_fns.get(settings.interpolation_mode, calculate_average_color)
    await websocket.accept()
    logger.info(f"KC test WS connected for {target_id} (fps={fps})")
    # Use the shared LiveStreamManager so we share the capture stream with
    # running LED targets instead of creating a competing DXGI duplicator.
    live_stream_mgr = processor_manager_inst._live_stream_manager
    live_stream = None
    try:
        live_stream = await asyncio.to_thread(
            live_stream_mgr.acquire, target.picture_source_id
        )
        logger.info(f"KC test WS acquired shared live stream for {target.picture_source_id}")
        prev_frame_ref = None
        while True:
            loop_start = time.monotonic()
            try:
                capture = await asyncio.to_thread(live_stream.get_latest_frame)
                if capture is None or capture.image is None:
                    await asyncio.sleep(frame_interval)
                    continue
                # Skip if same frame object (no new capture yet)
                if capture is prev_frame_ref:
                    await asyncio.sleep(frame_interval * 0.5)
                    continue
                prev_frame_ref = capture
                pil_image = Image.fromarray(capture.image) if isinstance(capture.image, np.ndarray) else None
                if pil_image is None:
                    await asyncio.sleep(frame_interval)
                    continue
                # Apply postprocessing (if the source chain has PP templates)
                chain = source_store_inst.resolve_stream_chain(target.picture_source_id)
                pp_template_ids = chain.get("postprocessing_template_ids", [])
                if pp_template_ids and pp_template_store_inst:
                    img_array = np.array(pil_image)
                    image_pool = ImagePool()
                    for pp_id in pp_template_ids:
                        try:
                            pp_template = pp_template_store_inst.get_template(pp_id)
                        except ValueError:
                            continue
                        flat_filters = pp_template_store_inst.resolve_filter_instances(pp_template.filters)
                        for fi in flat_filters:
                            try:
                                f = FilterRegistry.create_instance(fi.filter_id, fi.options)
                                result = f.process_image(img_array, image_pool)
                                if result is not None:
                                    img_array = result
                            except ValueError:
                                pass
                        pil_image = Image.fromarray(img_array)
                # Extract colors
                img_array = np.array(pil_image)
                h, w = img_array.shape[:2]
                result_rects = []
                for rect in rectangles:
                    px_x = max(0, int(rect.x * w))
                    px_y = max(0, int(rect.y * h))
                    px_w = max(1, int(rect.width * w))
                    px_h = max(1, int(rect.height * h))
                    px_x = min(px_x, w - 1)
                    px_y = min(px_y, h - 1)
                    px_w = min(px_w, w - px_x)
                    px_h = min(px_h, h - px_y)
                    sub_img = img_array[px_y:px_y + px_h, px_x:px_x + px_w]
                    r, g, b = calc_fn(sub_img)
                    result_rects.append({
                        "name": rect.name,
                        "x": rect.x,
                        "y": rect.y,
                        "width": rect.width,
                        "height": rect.height,
                        "color": {"r": r, "g": g, "b": b, "hex": f"#{r:02x}{g:02x}{b:02x}"},
                    })
                # Encode frame as JPEG
                if preview_width and pil_image.width > preview_width:
                    ratio = preview_width / pil_image.width
                    thumb = pil_image.resize((preview_width, int(pil_image.height * ratio)), Image.LANCZOS)
                else:
                    thumb = pil_image
                buf = io.BytesIO()
                thumb.save(buf, format="JPEG", quality=85)
                b64 = base64.b64encode(buf.getvalue()).decode()
                await websocket.send_text(_json.dumps({
                    "type": "frame",
                    "image": f"data:image/jpeg;base64,{b64}",
                    "rectangles": result_rects,
                    "pattern_template_name": pattern_tmpl.name,
                    "interpolation_mode": settings.interpolation_mode,
                }))
            except (WebSocketDisconnect, Exception) as inner_e:
                if isinstance(inner_e, WebSocketDisconnect):
                    raise
                logger.warning(f"KC test WS frame error for {target_id}: {inner_e}")
            elapsed = time.monotonic() - loop_start
            sleep_time = frame_interval - elapsed
            if sleep_time > 0:
                await asyncio.sleep(sleep_time)
    except WebSocketDisconnect:
        logger.info(f"KC test WS disconnected for {target_id}")
    except Exception as e:
        logger.error(f"KC test WS error for {target_id}: {e}", exc_info=True)
    finally:
        if live_stream is not None:
            try:
                await asyncio.to_thread(
                    live_stream_mgr.release, target.picture_source_id
                )
            except Exception:
                pass
        logger.info(f"KC test WS closed for {target_id}")
@router.websocket("/api/v1/output-targets/{target_id}/ws")
 async def target_colors_ws(
    websocket: WebSocket,
    target_id: str,
    token: str = Query(""),
 ):
    """WebSocket for real-time key color updates. Auth via ?token=<api_key>."""
    from wled_controller.api.auth import verify_ws_token
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    manager = get_processor_manager()
    try:
        manager.add_kc_ws_client(target_id, websocket)
    except ValueError:
        await websocket.close(code=4004, reason="Target not found")
        return
    try:
        while True:
            # Keep alive — wait for client messages (or disconnect)
            await websocket.receive_text()
    except WebSocketDisconnect:
        pass
    finally:
        manager.remove_kc_ws_client(target_id, websocket)
--- a/server/src/wled_controller/api/routes/picture_sources.py
+++ b/server/src/wled_controller/api/routes/picture_sources.py
@@ -584,7 +584,7 @@ async def test_picture_source_ws(
    preview_width: int = Query(0),
 ):
    """WebSocket for picture source test with intermediate frame previews."""
-    from wled_controller.api.routes._test_helpers import (
+    from wled_controller.api.routes._preview_helpers import (
        authenticate_ws_token,
        stream_capture_test,
    )
--- a/server/src/wled_controller/api/routes/postprocessing.py
+++ b/server/src/wled_controller/api/routes/postprocessing.py
@@ -365,7 +365,7 @@ async def test_pp_template_ws(
    preview_width: int = Query(0),
 ):
    """WebSocket for PP template test with intermediate frame previews."""
-    from wled_controller.api.routes._test_helpers import (
+    from wled_controller.api.routes._preview_helpers import (
        authenticate_ws_token,
        stream_capture_test,
    )
--- a/server/src/wled_controller/api/routes/system.py
+++ b/server/src/wled_controller/api/routes/system.py
@@ -1,26 +1,21 @@
-"""System routes: health, version, displays, performance, backup/restore, ADB."""
+"""System routes: health, version, displays, performance, tags, api-keys.
 Backup/restore and settings routes are in backup.py and system_settings.py.
 """
 import asyncio
 import io
 import json
 import logging
 import platform
 import subprocess
 import sys
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 import psutil
-from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile, WebSocket, WebSocketDisconnect
+from fastapi import APIRouter, Depends, HTTPException, Query
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 from wled_controller import __version__
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.dependencies import (
    get_auto_backup_engine,
    get_audio_source_store,
    get_audio_template_store,
    get_automation_store,
@@ -37,29 +32,22 @@ from wled_controller.api.dependencies import (
    get_value_source_store,
 )
 from wled_controller.api.schemas.system import (
    AutoBackupSettings,
    AutoBackupStatusResponse,
    BackupFileInfo,
    BackupListResponse,
    DisplayInfo,
    DisplayListResponse,
    ExternalUrlRequest,
    ExternalUrlResponse,
    GpuInfo,
    HealthResponse,
    LogLevelRequest,
    LogLevelResponse,
    MQTTSettingsRequest,
    MQTTSettingsResponse,
    PerformanceResponse,
    ProcessListResponse,
    RestoreResponse,
    VersionResponse,
 )
-from wled_controller.core.backup.auto_backup import AutoBackupEngine
+from wled_controller.config import get_config, is_demo_mode
 from wled_controller.config import get_config
 from wled_controller.core.capture.screen_capture import get_available_displays
-from wled_controller.utils import atomic_write_json, get_logger
+from wled_controller.utils import get_logger
 from wled_controller.storage.base_store import EntityNotFoundError
 # Re-export STORE_MAP and load_external_url so existing callers still work
 from wled_controller.api.routes.backup import STORE_MAP  # noqa: F401
 from wled_controller.api.routes.system_settings import load_external_url  # noqa: F401
 logger = get_logger(__name__)
@@ -67,8 +55,7 @@ logger = get_logger(__name__)
 psutil.cpu_percent(interval=None)
 # GPU monitoring (initialized once in utils.gpu, shared with metrics_history)
-from wled_controller.utils.gpu import nvml_available as _nvml_available, nvml as _nvml, nvml_handle as _nvml_handle
+from wled_controller.utils.gpu import nvml_available as _nvml_available, nvml as _nvml, nvml_handle as _nvml_handle  # noqa: E402
 from wled_controller.storage.base_store import EntityNotFoundError
 def _get_cpu_name() -> str | None:
@@ -113,12 +100,13 @@ async def health_check():
    Returns basic health information including status, version, and timestamp.
    """
-    logger.info("Health check requested")
+    logger.debug("Health check requested")
    return HealthResponse(
        status="healthy",
        timestamp=datetime.now(timezone.utc),
        version=__version__,
        demo_mode=get_config().demo,
    )
@@ -128,12 +116,13 @@ async def get_version():
    Returns application version, Python version, and API version.
    """
-    logger.info("Version info requested")
+    logger.debug("Version info requested")
    return VersionResponse(
        version=__version__,
        python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
        api_version="v1",
        demo_mode=get_config().demo,
    )
@@ -176,11 +165,20 @@ async def get_displays(
    logger.info(f"Listing available displays (engine_type={engine_type})")
    try:
        if engine_type:
        from wled_controller.core.capture_engines import EngineRegistry
        if engine_type:
            engine_cls = EngineRegistry.get_engine(engine_type)
            display_dataclasses = await asyncio.to_thread(engine_cls.get_available_displays)
        elif is_demo_mode():
            # In demo mode, use the best available engine (demo engine at priority 1000)
            # instead of the mss-based real display detection
            best = EngineRegistry.get_best_available_engine()
            if best:
                engine_cls = EngineRegistry.get_engine(best)
                display_dataclasses = await asyncio.to_thread(engine_cls.get_available_displays)
            else:
                display_dataclasses = await asyncio.to_thread(get_available_displays)
        else:
            display_dataclasses = await asyncio.to_thread(get_available_displays)
@@ -297,52 +295,6 @@ async def get_metrics_history(
    return manager.metrics_history.get_history()
 # ---------------------------------------------------------------------------
 # Configuration backup / restore
 # ---------------------------------------------------------------------------
 # Mapping: logical store name → StorageConfig attribute name
 STORE_MAP = {
    "devices": "devices_file",
    "capture_templates": "templates_file",
    "postprocessing_templates": "postprocessing_templates_file",
    "picture_sources": "picture_sources_file",
    "output_targets": "output_targets_file",
    "pattern_templates": "pattern_templates_file",
    "color_strip_sources": "color_strip_sources_file",
    "audio_sources": "audio_sources_file",
    "audio_templates": "audio_templates_file",
    "value_sources": "value_sources_file",
    "sync_clocks": "sync_clocks_file",
    "color_strip_processing_templates": "color_strip_processing_templates_file",
    "automations": "automations_file",
    "scene_presets": "scene_presets_file",
 }
 _SERVER_DIR = Path(__file__).resolve().parents[4]
 def _schedule_restart() -> None:
    """Spawn a restart script after a short delay so the HTTP response completes."""
    def _restart():
        import time
        time.sleep(1)
        if sys.platform == "win32":
            subprocess.Popen(
                ["powershell", "-ExecutionPolicy", "Bypass", "-File",
                 str(_SERVER_DIR / "restart.ps1")],
                creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP,
            )
        else:
            subprocess.Popen(
                ["bash", str(_SERVER_DIR / "restart.sh")],
                start_new_session=True,
            )
    threading.Thread(target=_restart, daemon=True).start()
@router.get("/api/v1/system/api-keys", tags=["System"])
 def list_api_keys(_: AuthRequired):
    """List API key labels (read-only; keys are defined in the YAML config file)."""
@@ -352,632 +304,3 @@ def list_api_keys(_: AuthRequired):
        for label, key in config.auth.api_keys.items()
    ]
    return {"keys": keys, "count": len(keys)}
@router.get("/api/v1/system/export/{store_key}", tags=["System"])
 def export_store(store_key: str, _: AuthRequired):
    """Download a single entity store as a JSON file."""
    if store_key not in STORE_MAP:
        raise HTTPException(
            status_code=404,
            detail=f"Unknown store '{store_key}'. Valid keys: {sorted(STORE_MAP.keys())}",
        )
    config = get_config()
    file_path = Path(getattr(config.storage, STORE_MAP[store_key]))
    if file_path.exists():
        with open(file_path, "r", encoding="utf-8") as f:
            data = json.load(f)
    else:
        data = {}
    export = {
        "meta": {
            "format": "ledgrab-partial-export",
            "format_version": 1,
            "store_key": store_key,
            "app_version": __version__,
            "created_at": datetime.now(timezone.utc).isoformat() + "Z",
        },
        "store": data,
    }
    content = json.dumps(export, indent=2, ensure_ascii=False)
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M%S")
    filename = f"ledgrab-{store_key}-{timestamp}.json"
    return StreamingResponse(
        io.BytesIO(content.encode("utf-8")),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.post("/api/v1/system/import/{store_key}", tags=["System"])
 async def import_store(
    store_key: str,
    _: AuthRequired,
    file: UploadFile = File(...),
    merge: bool = Query(False, description="Merge into existing data instead of replacing"),
 ):
    """Upload a partial export file to replace or merge one entity store. Triggers server restart."""
    if store_key not in STORE_MAP:
        raise HTTPException(
            status_code=404,
            detail=f"Unknown store '{store_key}'. Valid keys: {sorted(STORE_MAP.keys())}",
        )
    try:
        raw = await file.read()
        if len(raw) > 10 * 1024 * 1024:
            raise HTTPException(status_code=400, detail="File too large (max 10 MB)")
        payload = json.loads(raw)
    except json.JSONDecodeError as e:
        raise HTTPException(status_code=400, detail=f"Invalid JSON: {e}")
    # Support both full-backup format and partial-export format
    if "stores" in payload and isinstance(payload.get("meta"), dict):
        # Full backup: extract the specific store
        if payload["meta"].get("format") not in ("ledgrab-backup",):
            raise HTTPException(status_code=400, detail="Not a valid LED Grab backup or partial export file")
        stores = payload.get("stores", {})
        if store_key not in stores:
            raise HTTPException(status_code=400, detail=f"Backup does not contain store '{store_key}'")
        incoming = stores[store_key]
    elif isinstance(payload.get("meta"), dict) and payload["meta"].get("format") == "ledgrab-partial-export":
        # Partial export format
        if payload["meta"].get("store_key") != store_key:
            raise HTTPException(
                status_code=400,
                detail=f"File is for store '{payload['meta']['store_key']}', not '{store_key}'",
            )
        incoming = payload.get("store", {})
    else:
        raise HTTPException(status_code=400, detail="Not a valid LED Grab backup or partial export file")
    if not isinstance(incoming, dict):
        raise HTTPException(status_code=400, detail="Store data must be a JSON object")
    config = get_config()
    file_path = Path(getattr(config.storage, STORE_MAP[store_key]))
    def _write():
        if merge and file_path.exists():
            with open(file_path, "r", encoding="utf-8") as f:
                existing = json.load(f)
            if isinstance(existing, dict):
                existing.update(incoming)
                atomic_write_json(file_path, existing)
                return len(existing)
        atomic_write_json(file_path, incoming)
        return len(incoming)
    count = await asyncio.to_thread(_write)
    logger.info(f"Imported store '{store_key}' ({count} entries, merge={merge}). Scheduling restart...")
    _schedule_restart()
    return {
        "status": "imported",
        "store_key": store_key,
        "entries": count,
        "merge": merge,
        "restart_scheduled": True,
        "message": f"Imported {count} entries for '{store_key}'. Server restarting...",
    }
@router.get("/api/v1/system/backup", tags=["System"])
 def backup_config(_: AuthRequired):
    """Download all configuration as a single JSON backup file."""
    config = get_config()
    stores = {}
    for store_key, config_attr in STORE_MAP.items():
        file_path = Path(getattr(config.storage, config_attr))
        if file_path.exists():
            with open(file_path, "r", encoding="utf-8") as f:
                stores[store_key] = json.load(f)
        else:
            stores[store_key] = {}
    backup = {
        "meta": {
            "format": "ledgrab-backup",
            "format_version": 1,
            "app_version": __version__,
            "created_at": datetime.now(timezone.utc).isoformat() + "Z",
            "store_count": len(stores),
        },
        "stores": stores,
    }
    content = json.dumps(backup, indent=2, ensure_ascii=False)
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M%S")
    filename = f"ledgrab-backup-{timestamp}.json"
    return StreamingResponse(
        io.BytesIO(content.encode("utf-8")),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.post("/api/v1/system/restart", tags=["System"])
 def restart_server(_: AuthRequired):
    """Schedule a server restart and return immediately."""
    _schedule_restart()
    return {"status": "restarting"}
@router.post("/api/v1/system/restore", response_model=RestoreResponse, tags=["System"])
 async def restore_config(
    _: AuthRequired,
    file: UploadFile = File(...),
 ):
    """Upload a backup file to restore all configuration. Triggers server restart."""
    # Read and parse
    try:
        raw = await file.read()
        if len(raw) > 10 * 1024 * 1024:  # 10 MB limit
            raise HTTPException(status_code=400, detail="Backup file too large (max 10 MB)")
        backup = json.loads(raw)
    except json.JSONDecodeError as e:
        raise HTTPException(status_code=400, detail=f"Invalid JSON file: {e}")
    # Validate envelope
    meta = backup.get("meta")
    if not isinstance(meta, dict) or meta.get("format") != "ledgrab-backup":
        raise HTTPException(status_code=400, detail="Not a valid LED Grab backup file")
    fmt_version = meta.get("format_version", 0)
    if fmt_version > 1:
        raise HTTPException(
            status_code=400,
            detail=f"Backup format version {fmt_version} is not supported by this server version",
        )
    stores = backup.get("stores")
    if not isinstance(stores, dict):
        raise HTTPException(status_code=400, detail="Backup file missing 'stores' section")
    known_keys = set(STORE_MAP.keys())
    present_keys = known_keys & set(stores.keys())
    if not present_keys:
        raise HTTPException(status_code=400, detail="Backup contains no recognized store data")
    for key in present_keys:
        if not isinstance(stores[key], dict):
            raise HTTPException(status_code=400, detail=f"Store '{key}' in backup is not a valid JSON object")
    # Write store files atomically (in thread to avoid blocking event loop)
    config = get_config()
    def _write_stores():
        count = 0
        for store_key, config_attr in STORE_MAP.items():
            if store_key in stores:
                file_path = Path(getattr(config.storage, config_attr))
                atomic_write_json(file_path, stores[store_key])
                count += 1
                logger.info(f"Restored store: {store_key} -> {file_path}")
        return count
    written = await asyncio.to_thread(_write_stores)
    logger.info(f"Restore complete: {written}/{len(STORE_MAP)} stores written. Scheduling restart...")
    _schedule_restart()
    missing = known_keys - present_keys
    return RestoreResponse(
        status="restored",
        stores_written=written,
        stores_total=len(STORE_MAP),
        missing_stores=sorted(missing) if missing else [],
        restart_scheduled=True,
        message=f"Restored {written} stores. Server restarting...",
    )
 # ---------------------------------------------------------------------------
 # Auto-backup settings & saved backups
 # ---------------------------------------------------------------------------
@router.get(
    "/api/v1/system/auto-backup/settings",
    response_model=AutoBackupStatusResponse,
    tags=["System"],
 )
 async def get_auto_backup_settings(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Get auto-backup settings and status."""
    return engine.get_settings()
@router.put(
    "/api/v1/system/auto-backup/settings",
    response_model=AutoBackupStatusResponse,
    tags=["System"],
 )
 async def update_auto_backup_settings(
    _: AuthRequired,
    body: AutoBackupSettings,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Update auto-backup settings (enable/disable, interval, max backups)."""
    return await engine.update_settings(
        enabled=body.enabled,
        interval_hours=body.interval_hours,
        max_backups=body.max_backups,
    )
@router.post("/api/v1/system/auto-backup/trigger", tags=["System"])
 async def trigger_backup(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Manually trigger a backup now."""
    backup = await engine.trigger_backup()
    return {"status": "ok", "backup": backup}
@router.get(
    "/api/v1/system/backups",
    response_model=BackupListResponse,
    tags=["System"],
 )
 async def list_backups(
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """List all saved backup files."""
    backups = engine.list_backups()
    return BackupListResponse(
        backups=[BackupFileInfo(**b) for b in backups],
        count=len(backups),
    )
@router.get("/api/v1/system/backups/{filename}", tags=["System"])
 def download_saved_backup(
    filename: str,
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Download a specific saved backup file."""
    try:
        path = engine.get_backup_path(filename)
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(status_code=404, detail=str(e))
    content = path.read_bytes()
    return StreamingResponse(
        io.BytesIO(content),
        media_type="application/json",
        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
    )
@router.delete("/api/v1/system/backups/{filename}", tags=["System"])
 async def delete_saved_backup(
    filename: str,
    _: AuthRequired,
    engine: AutoBackupEngine = Depends(get_auto_backup_engine),
 ):
    """Delete a specific saved backup file."""
    try:
        engine.delete_backup(filename)
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(status_code=404, detail=str(e))
    return {"status": "deleted", "filename": filename}
 # ---------------------------------------------------------------------------
 # MQTT settings
 # ---------------------------------------------------------------------------
 _MQTT_SETTINGS_FILE: Path | None = None
 def _get_mqtt_settings_path() -> Path:
    global _MQTT_SETTINGS_FILE
    if _MQTT_SETTINGS_FILE is None:
        cfg = get_config()
        # Derive the data directory from any known storage file path
        data_dir = Path(cfg.storage.devices_file).parent
        _MQTT_SETTINGS_FILE = data_dir / "mqtt_settings.json"
    return _MQTT_SETTINGS_FILE
 def _load_mqtt_settings() -> dict:
    """Load MQTT settings: YAML config defaults overridden by JSON overrides file."""
    cfg = get_config()
    defaults = {
        "enabled": cfg.mqtt.enabled,
        "broker_host": cfg.mqtt.broker_host,
        "broker_port": cfg.mqtt.broker_port,
        "username": cfg.mqtt.username,
        "password": cfg.mqtt.password,
        "client_id": cfg.mqtt.client_id,
        "base_topic": cfg.mqtt.base_topic,
    }
    path = _get_mqtt_settings_path()
    if path.exists():
        try:
            with open(path, "r", encoding="utf-8") as f:
                overrides = json.load(f)
            defaults.update(overrides)
        except Exception as e:
            logger.warning(f"Failed to load MQTT settings override file: {e}")
    return defaults
 def _save_mqtt_settings(settings: dict) -> None:
    """Persist MQTT settings to the JSON override file."""
    from wled_controller.utils import atomic_write_json
    atomic_write_json(_get_mqtt_settings_path(), settings)
@router.get(
    "/api/v1/system/mqtt/settings",
    response_model=MQTTSettingsResponse,
    tags=["System"],
 )
 async def get_mqtt_settings(_: AuthRequired):
    """Get current MQTT broker settings. Password is masked."""
    s = _load_mqtt_settings()
    return MQTTSettingsResponse(
        enabled=s["enabled"],
        broker_host=s["broker_host"],
        broker_port=s["broker_port"],
        username=s["username"],
        password_set=bool(s.get("password")),
        client_id=s["client_id"],
        base_topic=s["base_topic"],
    )
@router.put(
    "/api/v1/system/mqtt/settings",
    response_model=MQTTSettingsResponse,
    tags=["System"],
 )
 async def update_mqtt_settings(_: AuthRequired, body: MQTTSettingsRequest):
    """Update MQTT broker settings. If password is empty string, the existing password is preserved."""
    current = _load_mqtt_settings()
    # If caller sends an empty password, keep the existing one
    password = body.password if body.password else current.get("password", "")
    new_settings = {
        "enabled": body.enabled,
        "broker_host": body.broker_host,
        "broker_port": body.broker_port,
        "username": body.username,
        "password": password,
        "client_id": body.client_id,
        "base_topic": body.base_topic,
    }
    _save_mqtt_settings(new_settings)
    logger.info("MQTT settings updated")
    return MQTTSettingsResponse(
        enabled=new_settings["enabled"],
        broker_host=new_settings["broker_host"],
        broker_port=new_settings["broker_port"],
        username=new_settings["username"],
        password_set=bool(new_settings["password"]),
        client_id=new_settings["client_id"],
        base_topic=new_settings["base_topic"],
    )
 # ---------------------------------------------------------------------------
 # External URL setting
 # ---------------------------------------------------------------------------
 _EXTERNAL_URL_FILE: Path | None = None
 def _get_external_url_path() -> Path:
    global _EXTERNAL_URL_FILE
    if _EXTERNAL_URL_FILE is None:
        cfg = get_config()
        data_dir = Path(cfg.storage.devices_file).parent
        _EXTERNAL_URL_FILE = data_dir / "external_url.json"
    return _EXTERNAL_URL_FILE
 def load_external_url() -> str:
    """Load the external URL setting. Returns empty string if not set."""
    path = _get_external_url_path()
    if path.exists():
        try:
            with open(path, "r", encoding="utf-8") as f:
                data = json.load(f)
            return data.get("external_url", "")
        except Exception:
            pass
    return ""
 def _save_external_url(url: str) -> None:
    from wled_controller.utils import atomic_write_json
    atomic_write_json(_get_external_url_path(), {"external_url": url})
@router.get(
    "/api/v1/system/external-url",
    response_model=ExternalUrlResponse,
    tags=["System"],
 )
 async def get_external_url(_: AuthRequired):
    """Get the configured external base URL."""
    return ExternalUrlResponse(external_url=load_external_url())
@router.put(
    "/api/v1/system/external-url",
    response_model=ExternalUrlResponse,
    tags=["System"],
 )
 async def update_external_url(_: AuthRequired, body: ExternalUrlRequest):
    """Set the external base URL used in webhook URLs and other user-visible URLs."""
    url = body.external_url.strip().rstrip("/")
    _save_external_url(url)
    logger.info("External URL updated: %s", url or "(cleared)")
    return ExternalUrlResponse(external_url=url)
 # ---------------------------------------------------------------------------
 # Live log viewer WebSocket
 # ---------------------------------------------------------------------------
@router.websocket("/api/v1/system/logs/ws")
 async def logs_ws(
    websocket: WebSocket,
    token: str = Query(""),
 ):
    """WebSocket that streams server log lines in real time.
    Auth via ``?token=<api_key>``.  On connect, sends the last ~500 buffered
    lines as individual text messages, then pushes new lines as they appear.
    """
    from wled_controller.api.auth import verify_ws_token
    from wled_controller.utils import log_broadcaster
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    # Ensure the broadcaster knows the event loop (may be first connection)
    log_broadcaster.ensure_loop()
    # Subscribe *before* reading the backlog so no lines slip through
    queue = log_broadcaster.subscribe()
    try:
        # Send backlog first
        for line in log_broadcaster.get_backlog():
            await websocket.send_text(line)
        # Stream new lines
        while True:
            try:
                line = await asyncio.wait_for(queue.get(), timeout=30.0)
                await websocket.send_text(line)
            except asyncio.TimeoutError:
                # Send a keepalive ping so the connection stays alive
                try:
                    await websocket.send_text("")
                except Exception:
                    break
    except WebSocketDisconnect:
        pass
    except Exception:
        pass
    finally:
        log_broadcaster.unsubscribe(queue)
 # ---------------------------------------------------------------------------
 # ADB helpers (for Android / scrcpy engine)
 # ---------------------------------------------------------------------------
 class AdbConnectRequest(BaseModel):
    address: str
 def _get_adb_path() -> str:
    """Get the adb binary path from the scrcpy engine's resolver."""
    from wled_controller.core.capture_engines.scrcpy_engine import _get_adb
    return _get_adb()
@router.post("/api/v1/adb/connect", tags=["ADB"])
 async def adb_connect(_: AuthRequired, request: AdbConnectRequest):
    """Connect to a WiFi ADB device by IP address.
    Appends ``:5555`` if no port is specified.
    """
    address = request.address.strip()
    if not address:
        raise HTTPException(status_code=400, detail="Address is required")
    if ":" not in address:
        address = f"{address}:5555"
    adb = _get_adb_path()
    logger.info(f"Connecting ADB device: {address}")
    try:
        proc = await asyncio.create_subprocess_exec(
            adb, "connect", address,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
        output = (stdout.decode() + stderr.decode()).strip()
        if "connected" in output.lower():
            return {"status": "connected", "address": address, "message": output}
        raise HTTPException(status_code=400, detail=output or "Connection failed")
    except FileNotFoundError:
        raise HTTPException(
            status_code=500,
            detail="adb not found on PATH. Install Android SDK Platform-Tools.",
        )
    except asyncio.TimeoutError:
        raise HTTPException(status_code=504, detail="ADB connect timed out")
@router.post("/api/v1/adb/disconnect", tags=["ADB"])
 async def adb_disconnect(_: AuthRequired, request: AdbConnectRequest):
    """Disconnect a WiFi ADB device."""
    address = request.address.strip()
    if not address:
        raise HTTPException(status_code=400, detail="Address is required")
    adb = _get_adb_path()
    logger.info(f"Disconnecting ADB device: {address}")
    try:
        proc = await asyncio.create_subprocess_exec(
            adb, "disconnect", address,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
        return {"status": "disconnected", "message": stdout.decode().strip()}
    except FileNotFoundError:
        raise HTTPException(status_code=500, detail="adb not found on PATH")
    except asyncio.TimeoutError:
        raise HTTPException(status_code=504, detail="ADB disconnect timed out")
 # ─── Log level ─────────────────────────────────────────────────
 _VALID_LOG_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
@router.get("/api/v1/system/log-level", response_model=LogLevelResponse, tags=["System"])
 async def get_log_level(_: AuthRequired):
    """Get the current root logger log level."""
    level_int = logging.getLogger().getEffectiveLevel()
    return LogLevelResponse(level=logging.getLevelName(level_int))
@router.put("/api/v1/system/log-level", response_model=LogLevelResponse, tags=["System"])
 async def set_log_level(_: AuthRequired, body: LogLevelRequest):
    """Change the root logger log level at runtime (no server restart required)."""
    level_name = body.level.upper()
    if level_name not in _VALID_LOG_LEVELS:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid log level '{body.level}'. Must be one of: {', '.join(sorted(_VALID_LOG_LEVELS))}",
        )
    level_int = getattr(logging, level_name)
    root = logging.getLogger()
    root.setLevel(level_int)
    # Also update all handlers so they actually emit at the new level
    for handler in root.handlers:
        handler.setLevel(level_int)
    logger.info("Log level changed to %s", level_name)
    return LogLevelResponse(level=level_name)
--- a/server/src/wled_controller/api/routes/system_settings.py
+++ b/server/src/wled_controller/api/routes/system_settings.py
@@ -0,0 +1,377 @@
 """System routes: MQTT, external URL, ADB, logs WebSocket, log level.
 Extracted from system.py to keep files under 800 lines.
 """
 import asyncio
 import json
 import logging
 import re
 from pathlib import Path
 from fastapi import APIRouter, HTTPException, Query, WebSocket, WebSocketDisconnect
 from pydantic import BaseModel
 from wled_controller.api.auth import AuthRequired
 from wled_controller.api.schemas.system import (
    ExternalUrlRequest,
    ExternalUrlResponse,
    LogLevelRequest,
    LogLevelResponse,
    MQTTSettingsRequest,
    MQTTSettingsResponse,
 )
 from wled_controller.config import get_config
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 router = APIRouter()
 # ---------------------------------------------------------------------------
 # MQTT settings
 # ---------------------------------------------------------------------------
 _MQTT_SETTINGS_FILE: Path | None = None
 def _get_mqtt_settings_path() -> Path:
    global _MQTT_SETTINGS_FILE
    if _MQTT_SETTINGS_FILE is None:
        cfg = get_config()
        # Derive the data directory from any known storage file path
        data_dir = Path(cfg.storage.devices_file).parent
        _MQTT_SETTINGS_FILE = data_dir / "mqtt_settings.json"
    return _MQTT_SETTINGS_FILE
 def _load_mqtt_settings() -> dict:
    """Load MQTT settings: YAML config defaults overridden by JSON overrides file."""
    cfg = get_config()
    defaults = {
        "enabled": cfg.mqtt.enabled,
        "broker_host": cfg.mqtt.broker_host,
        "broker_port": cfg.mqtt.broker_port,
        "username": cfg.mqtt.username,
        "password": cfg.mqtt.password,
        "client_id": cfg.mqtt.client_id,
        "base_topic": cfg.mqtt.base_topic,
    }
    path = _get_mqtt_settings_path()
    if path.exists():
        try:
            with open(path, "r", encoding="utf-8") as f:
                overrides = json.load(f)
            defaults.update(overrides)
        except Exception as e:
            logger.warning(f"Failed to load MQTT settings override file: {e}")
    return defaults
 def _save_mqtt_settings(settings: dict) -> None:
    """Persist MQTT settings to the JSON override file."""
    from wled_controller.utils import atomic_write_json
    atomic_write_json(_get_mqtt_settings_path(), settings)
@router.get(
    "/api/v1/system/mqtt/settings",
    response_model=MQTTSettingsResponse,
    tags=["System"],
 )
 async def get_mqtt_settings(_: AuthRequired):
    """Get current MQTT broker settings. Password is masked."""
    s = _load_mqtt_settings()
    return MQTTSettingsResponse(
        enabled=s["enabled"],
        broker_host=s["broker_host"],
        broker_port=s["broker_port"],
        username=s["username"],
        password_set=bool(s.get("password")),
        client_id=s["client_id"],
        base_topic=s["base_topic"],
    )
@router.put(
    "/api/v1/system/mqtt/settings",
    response_model=MQTTSettingsResponse,
    tags=["System"],
 )
 async def update_mqtt_settings(_: AuthRequired, body: MQTTSettingsRequest):
    """Update MQTT broker settings. If password is empty string, the existing password is preserved."""
    current = _load_mqtt_settings()
    # If caller sends an empty password, keep the existing one
    password = body.password if body.password else current.get("password", "")
    new_settings = {
        "enabled": body.enabled,
        "broker_host": body.broker_host,
        "broker_port": body.broker_port,
        "username": body.username,
        "password": password,
        "client_id": body.client_id,
        "base_topic": body.base_topic,
    }
    _save_mqtt_settings(new_settings)
    logger.info("MQTT settings updated")
    return MQTTSettingsResponse(
        enabled=new_settings["enabled"],
        broker_host=new_settings["broker_host"],
        broker_port=new_settings["broker_port"],
        username=new_settings["username"],
        password_set=bool(new_settings["password"]),
        client_id=new_settings["client_id"],
        base_topic=new_settings["base_topic"],
    )
 # ---------------------------------------------------------------------------
 # External URL setting
 # ---------------------------------------------------------------------------
 _EXTERNAL_URL_FILE: Path | None = None
 def _get_external_url_path() -> Path:
    global _EXTERNAL_URL_FILE
    if _EXTERNAL_URL_FILE is None:
        cfg = get_config()
        data_dir = Path(cfg.storage.devices_file).parent
        _EXTERNAL_URL_FILE = data_dir / "external_url.json"
    return _EXTERNAL_URL_FILE
 def load_external_url() -> str:
    """Load the external URL setting. Returns empty string if not set."""
    path = _get_external_url_path()
    if path.exists():
        try:
            with open(path, "r", encoding="utf-8") as f:
                data = json.load(f)
            return data.get("external_url", "")
        except Exception:
            pass
    return ""
 def _save_external_url(url: str) -> None:
    from wled_controller.utils import atomic_write_json
    atomic_write_json(_get_external_url_path(), {"external_url": url})
@router.get(
    "/api/v1/system/external-url",
    response_model=ExternalUrlResponse,
    tags=["System"],
 )
 async def get_external_url(_: AuthRequired):
    """Get the configured external base URL."""
    return ExternalUrlResponse(external_url=load_external_url())
@router.put(
    "/api/v1/system/external-url",
    response_model=ExternalUrlResponse,
    tags=["System"],
 )
 async def update_external_url(_: AuthRequired, body: ExternalUrlRequest):
    """Set the external base URL used in webhook URLs and other user-visible URLs."""
    url = body.external_url.strip().rstrip("/")
    _save_external_url(url)
    logger.info("External URL updated: %s", url or "(cleared)")
    return ExternalUrlResponse(external_url=url)
 # ---------------------------------------------------------------------------
 # Live log viewer WebSocket
 # ---------------------------------------------------------------------------
@router.websocket("/api/v1/system/logs/ws")
 async def logs_ws(
    websocket: WebSocket,
    token: str = Query(""),
 ):
    """WebSocket that streams server log lines in real time.
    Auth via ``?token=<api_key>``.  On connect, sends the last ~500 buffered
    lines as individual text messages, then pushes new lines as they appear.
    """
    from wled_controller.api.auth import verify_ws_token
    from wled_controller.utils import log_broadcaster
    if not verify_ws_token(token):
        await websocket.close(code=4001, reason="Unauthorized")
        return
    await websocket.accept()
    # Ensure the broadcaster knows the event loop (may be first connection)
    log_broadcaster.ensure_loop()
    # Subscribe *before* reading the backlog so no lines slip through
    queue = log_broadcaster.subscribe()
    try:
        # Send backlog first
        for line in log_broadcaster.get_backlog():
            await websocket.send_text(line)
        # Stream new lines
        while True:
            try:
                line = await asyncio.wait_for(queue.get(), timeout=30.0)
                await websocket.send_text(line)
            except asyncio.TimeoutError:
                # Send a keepalive ping so the connection stays alive
                try:
                    await websocket.send_text("")
                except Exception:
                    break
    except WebSocketDisconnect:
        pass
    except Exception:
        pass
    finally:
        log_broadcaster.unsubscribe(queue)
 # ---------------------------------------------------------------------------
 # ADB helpers (for Android / scrcpy engine)
 # ---------------------------------------------------------------------------
 # Regex: IPv4 address with optional port, e.g. "192.168.1.5" or "192.168.1.5:5555"
 _ADB_ADDRESS_RE = re.compile(
    r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d{1,5})?$"
 )
 class AdbConnectRequest(BaseModel):
    address: str
 def _validate_adb_address(address: str) -> None:
    """Raise 400 if *address* is not a valid IP:port for ADB."""
    if not _ADB_ADDRESS_RE.match(address):
        raise HTTPException(
            status_code=400,
            detail=(
                f"Invalid ADB address '{address}'. "
                "Expected format: <IP> or <IP>:<port>, e.g. 192.168.1.5 or 192.168.1.5:5555"
            ),
        )
    # Validate each octet is 0-255 and port is 1-65535
    parts = address.split(":")
    ip_parts = parts[0].split(".")
    for octet in ip_parts:
        if not (0 <= int(octet) <= 255):
            raise HTTPException(
                status_code=400,
                detail=f"Invalid IP octet '{octet}' in address '{address}'. Each octet must be 0-255.",
            )
    if len(parts) == 2:
        port = int(parts[1])
        if not (1 <= port <= 65535):
            raise HTTPException(
                status_code=400,
                detail=f"Invalid port '{parts[1]}' in address '{address}'. Port must be 1-65535.",
            )
 def _get_adb_path() -> str:
    """Get the adb binary path from the scrcpy engine's resolver."""
    from wled_controller.core.capture_engines.scrcpy_engine import _get_adb
    return _get_adb()
@router.post("/api/v1/adb/connect", tags=["ADB"])
 async def adb_connect(_: AuthRequired, request: AdbConnectRequest):
    """Connect to a WiFi ADB device by IP address.
    Appends ``:5555`` if no port is specified.
    """
    address = request.address.strip()
    if not address:
        raise HTTPException(status_code=400, detail="Address is required")
    _validate_adb_address(address)
    if ":" not in address:
        address = f"{address}:5555"
    adb = _get_adb_path()
    logger.info(f"Connecting ADB device: {address}")
    try:
        proc = await asyncio.create_subprocess_exec(
            adb, "connect", address,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
        output = (stdout.decode() + stderr.decode()).strip()
        if "connected" in output.lower():
            return {"status": "connected", "address": address, "message": output}
        raise HTTPException(status_code=400, detail=output or "Connection failed")
    except FileNotFoundError:
        raise HTTPException(
            status_code=500,
            detail="adb not found on PATH. Install Android SDK Platform-Tools.",
        )
    except asyncio.TimeoutError:
        raise HTTPException(status_code=504, detail="ADB connect timed out")
@router.post("/api/v1/adb/disconnect", tags=["ADB"])
 async def adb_disconnect(_: AuthRequired, request: AdbConnectRequest):
    """Disconnect a WiFi ADB device."""
    address = request.address.strip()
    if not address:
        raise HTTPException(status_code=400, detail="Address is required")
    adb = _get_adb_path()
    logger.info(f"Disconnecting ADB device: {address}")
    try:
        proc = await asyncio.create_subprocess_exec(
            adb, "disconnect", address,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
        return {"status": "disconnected", "message": stdout.decode().strip()}
    except FileNotFoundError:
        raise HTTPException(status_code=500, detail="adb not found on PATH")
    except asyncio.TimeoutError:
        raise HTTPException(status_code=504, detail="ADB disconnect timed out")
 # --- Log level -----
 _VALID_LOG_LEVELS = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
@router.get("/api/v1/system/log-level", response_model=LogLevelResponse, tags=["System"])
 async def get_log_level(_: AuthRequired):
    """Get the current root logger log level."""
    level_int = logging.getLogger().getEffectiveLevel()
    return LogLevelResponse(level=logging.getLevelName(level_int))
@router.put("/api/v1/system/log-level", response_model=LogLevelResponse, tags=["System"])
 async def set_log_level(_: AuthRequired, body: LogLevelRequest):
    """Change the root logger log level at runtime (no server restart required)."""
    level_name = body.level.upper()
    if level_name not in _VALID_LOG_LEVELS:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid log level '{body.level}'. Must be one of: {', '.join(sorted(_VALID_LOG_LEVELS))}",
        )
    level_int = getattr(logging, level_name)
    root = logging.getLogger()
    root.setLevel(level_int)
    # Also update all handlers so they actually emit at the new level
    for handler in root.handlers:
        handler.setLevel(level_int)
    logger.info("Log level changed to %s", level_name)
    return LogLevelResponse(level=level_name)
--- a/server/src/wled_controller/api/routes/templates.py
+++ b/server/src/wled_controller/api/routes/templates.py
@@ -403,7 +403,7 @@ async def test_template_ws(
    Config is sent as the first client message (JSON with engine_type,
    engine_config, display_index, capture_duration).
    """
-    from wled_controller.api.routes._test_helpers import (
+    from wled_controller.api.routes._preview_helpers import (
        authenticate_ws_token,
        stream_capture_test,
    )
--- a/server/src/wled_controller/api/routes/webhooks.py
+++ b/server/src/wled_controller/api/routes/webhooks.py
@@ -6,7 +6,10 @@ automations that have a webhook condition.  No API-key auth is required —
 the secret token itself authenticates the caller.
 """
-from fastapi import APIRouter, Depends, HTTPException
+import time
 from collections import defaultdict
 from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel, Field
 from wled_controller.api.dependencies import get_automation_engine, get_automation_store
@@ -18,6 +21,28 @@ from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 router = APIRouter()
 # ---------------------------------------------------------------------------
 # Simple in-memory rate limiter: 30 requests per 60-second window per IP
 # ---------------------------------------------------------------------------
 _RATE_LIMIT = 30
 _RATE_WINDOW = 60.0  # seconds
 _rate_hits: dict[str, list[float]] = defaultdict(list)
 def _check_rate_limit(client_ip: str) -> None:
    """Raise 429 if *client_ip* exceeded the webhook rate limit."""
    now = time.time()
    window_start = now - _RATE_WINDOW
    # Prune timestamps outside the window
    timestamps = _rate_hits[client_ip]
    _rate_hits[client_ip] = [t for t in timestamps if t > window_start]
    if len(_rate_hits[client_ip]) >= _RATE_LIMIT:
        raise HTTPException(
            status_code=429,
            detail="Rate limit exceeded. Max 30 webhook requests per minute.",
        )
    _rate_hits[client_ip].append(now)
 class WebhookPayload(BaseModel):
    action: str = Field(description="'activate' or 'deactivate'")
@@ -30,10 +55,13 @@ class WebhookPayload(BaseModel):
 async def handle_webhook(
    token: str,
    body: WebhookPayload,
    request: Request,
    store: AutomationStore = Depends(get_automation_store),
    engine: AutomationEngine = Depends(get_automation_engine),
 ):
    """Receive a webhook call and set the corresponding condition state."""
    _check_rate_limit(request.client.host if request.client else "unknown")
    if body.action not in ("activate", "deactivate"):
        raise HTTPException(status_code=400, detail="action must be 'activate' or 'deactivate'")
--- a/server/src/wled_controller/api/schemas/common.py
+++ b/server/src/wled_controller/api/schemas/common.py
@@ -1,7 +1,7 @@
 """Shared schemas used across multiple route modules."""
 from datetime import datetime
-from typing import Dict, List, Optional
+from typing import Dict, Optional
 from pydantic import BaseModel, Field
--- a/server/src/wled_controller/api/schemas/devices.py
+++ b/server/src/wled_controller/api/schemas/devices.py
@@ -144,6 +144,18 @@ class CalibrationTestModeResponse(BaseModel):
    device_id: str = Field(description="Device ID")
 class BrightnessRequest(BaseModel):
    """Request to set device brightness."""
    brightness: int = Field(ge=0, le=255, description="Brightness level (0-255)")
 class PowerRequest(BaseModel):
    """Request to set device power state."""
    power: bool = Field(description="Whether the device should be on (true) or off (false)")
 class DeviceResponse(BaseModel):
    """Device information response."""
--- a/server/src/wled_controller/api/schemas/system.py
+++ b/server/src/wled_controller/api/schemas/system.py
@@ -12,6 +12,7 @@ class HealthResponse(BaseModel):
    status: Literal["healthy", "unhealthy"] = Field(description="Service health status")
    timestamp: datetime = Field(description="Current server time")
    version: str = Field(description="Application version")
    demo_mode: bool = Field(default=False, description="Whether demo mode is active")
 class VersionResponse(BaseModel):
@@ -20,6 +21,7 @@ class VersionResponse(BaseModel):
    version: str = Field(description="Application version")
    python_version: str = Field(description="Python version")
    api_version: str = Field(description="API version")
    demo_mode: bool = Field(default=False, description="Whether demo mode is active")
 class DisplayInfo(BaseModel):
--- a/server/src/wled_controller/config.py
+++ b/server/src/wled_controller/config.py
@@ -73,12 +73,22 @@ class Config(BaseSettings):
        case_sensitive=False,
    )
    demo: bool = False
    server: ServerConfig = Field(default_factory=ServerConfig)
    auth: AuthConfig = Field(default_factory=AuthConfig)
    storage: StorageConfig = Field(default_factory=StorageConfig)
    mqtt: MQTTConfig = Field(default_factory=MQTTConfig)
    logging: LoggingConfig = Field(default_factory=LoggingConfig)
    def model_post_init(self, __context: object) -> None:
        """Override storage paths when demo mode is active."""
        if self.demo:
            for field_name in self.storage.model_fields:
                value = getattr(self.storage, field_name)
                if isinstance(value, str) and value.startswith("data/"):
                    setattr(self.storage, field_name, value.replace("data/", "data/demo/", 1))
    @classmethod
    def from_yaml(cls, config_path: str | Path) -> "Config":
        """Load configuration from YAML file.
@@ -104,8 +114,9 @@ class Config(BaseSettings):
        Tries to load from:
        1. Environment variable WLED_CONFIG_PATH
-        2. ./config/default_config.yaml
+        2. WLED_DEMO=true → ./config/demo_config.yaml (if it exists)
-        3. Default values
+        3. ./config/default_config.yaml
        4. Default values
        Returns:
            Config instance
@@ -115,6 +126,12 @@ class Config(BaseSettings):
        if config_path:
            return cls.from_yaml(config_path)
        # Demo mode: try dedicated demo config first
        if os.getenv("WLED_DEMO", "").lower() in ("true", "1", "yes"):
            demo_path = Path("config/demo_config.yaml")
            if demo_path.exists():
                return cls.from_yaml(demo_path)
        # Try default location
        default_path = Path("config/default_config.yaml")
        if default_path.exists():
@@ -149,3 +166,8 @@ def reload_config() -> Config:
    global config
    config = Config.load()
    return config
 def is_demo_mode() -> bool:
    """Check whether the application is running in demo mode."""
    return get_config().demo
--- a/server/src/wled_controller/core/audio/init.py
+++ b/server/src/wled_controller/core/audio/init.py
@@ -15,10 +15,12 @@ from wled_controller.core.audio.analysis import (
 )
 from wled_controller.core.audio.wasapi_engine import WasapiEngine, WasapiCaptureStream
 from wled_controller.core.audio.sounddevice_engine import SounddeviceEngine, SounddeviceCaptureStream
 from wled_controller.core.audio.demo_engine import DemoAudioEngine, DemoAudioCaptureStream
 # Auto-register available engines
 AudioEngineRegistry.register(WasapiEngine)
 AudioEngineRegistry.register(SounddeviceEngine)
 AudioEngineRegistry.register(DemoAudioEngine)
 __all__ = [
    "AudioCaptureEngine",
@@ -34,4 +36,6 @@ __all__ = [
    "WasapiCaptureStream",
    "SounddeviceEngine",
    "SounddeviceCaptureStream",
    "DemoAudioEngine",
    "DemoAudioCaptureStream",
 ]
--- a/server/src/wled_controller/core/audio/analysis.py
+++ b/server/src/wled_controller/core/audio/analysis.py
@@ -141,7 +141,6 @@ class AudioAnalyzer:
        Returns:
            AudioAnalysis with spectrum, RMS, beat, etc.
        """
        chunk_size = self._chunk_size
        alpha = self._smoothing_alpha
        one_minus_alpha = 1.0 - alpha
--- a/server/src/wled_controller/core/audio/audio_capture.py
+++ b/server/src/wled_controller/core/audio/audio_capture.py
@@ -16,8 +16,6 @@ from typing import Any, Dict, List, Optional, Tuple
 from wled_controller.core.audio.analysis import (
    AudioAnalysis,
    AudioAnalyzer,
    DEFAULT_CHUNK_SIZE,
    DEFAULT_SAMPLE_RATE,
 )
 from wled_controller.core.audio.base import AudioCaptureStreamBase
 from wled_controller.core.audio.factory import AudioEngineRegistry
--- a/server/src/wled_controller/core/audio/demo_engine.py
+++ b/server/src/wled_controller/core/audio/demo_engine.py
@@ -0,0 +1,153 @@
 """Demo audio engine — virtual audio devices with synthetic audio data."""
 import time
 from typing import Any, Dict, List, Optional
 import numpy as np
 from wled_controller.config import is_demo_mode
 from wled_controller.core.audio.base import (
    AudioCaptureEngine,
    AudioCaptureStreamBase,
    AudioDeviceInfo,
 )
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 # Virtual audio device definitions: (name, is_loopback, channels, samplerate)
 _VIRTUAL_DEVICES = [
    ("Demo Microphone", False, 2, 44100.0),
    ("Demo System Audio", True, 2, 44100.0),
 ]
 class DemoAudioCaptureStream(AudioCaptureStreamBase):
    """Demo audio capture stream that produces synthetic music-like audio.
    Generates a mix of sine waves with slowly varying frequencies to
    simulate beat-like patterns suitable for audio-reactive visualizations.
    """
    def __init__(self, device_index: int, is_loopback: bool, config: Dict[str, Any]):
        super().__init__(device_index, is_loopback, config)
        self._channels = 2
        self._sample_rate = 44100
        self._chunk_size = 1024
        self._phase = 0.0  # Accumulated phase in samples for continuity
    @property
    def channels(self) -> int:
        return self._channels
    @property
    def sample_rate(self) -> int:
        return self._sample_rate
    @property
    def chunk_size(self) -> int:
        return self._chunk_size
    def initialize(self) -> None:
        if self._initialized:
            return
        self._phase = 0.0
        self._initialized = True
        logger.info(
            f"Demo audio stream initialized "
            f"(device={self.device_index}, loopback={self.is_loopback})"
        )
    def cleanup(self) -> None:
        self._initialized = False
        logger.info(f"Demo audio stream cleaned up (device={self.device_index})")
    def read_chunk(self) -> Optional[np.ndarray]:
        if not self._initialized:
            return None
        t_now = time.time()
        n = self._chunk_size
        sr = self._sample_rate
        # Sample indices for this chunk (continuous across calls)
        t = (self._phase + np.arange(n, dtype=np.float64)) / sr
        self._phase += n
        # --- Synthetic "music" signal ---
        # Bass drum: ~80 Hz with slow amplitude envelope (~2 Hz beat)
        bass_freq = 80.0
        beat_rate = 2.0  # beats per second
        bass_env = np.maximum(0.0, np.sin(2.0 * np.pi * beat_rate * t)) ** 4
        bass = 0.5 * bass_env * np.sin(2.0 * np.pi * bass_freq * t)
        # Mid-range tone: slowly sweeping between 300-600 Hz
        mid_freq = 450.0 + 150.0 * np.sin(2.0 * np.pi * 0.1 * t_now)
        mid = 0.25 * np.sin(2.0 * np.pi * mid_freq * t)
        # High shimmer: ~3 kHz with faster modulation
        hi_freq = 3000.0 + 500.0 * np.sin(2.0 * np.pi * 0.3 * t_now)
        hi_env = 0.5 + 0.5 * np.sin(2.0 * np.pi * 4.0 * t)
        hi = 0.1 * hi_env * np.sin(2.0 * np.pi * hi_freq * t)
        # Mix mono signal
        mono = (bass + mid + hi).astype(np.float32)
        # Interleave stereo (identical L/R)
        stereo = np.empty(n * self._channels, dtype=np.float32)
        stereo[0::2] = mono
        stereo[1::2] = mono
        return stereo
 class DemoAudioEngine(AudioCaptureEngine):
    """Virtual audio engine for demo mode.
    Provides virtual audio devices and produces synthetic audio data
    so the full audio-reactive pipeline works without real audio hardware.
    """
    ENGINE_TYPE = "demo"
    ENGINE_PRIORITY = 1000  # Highest priority in demo mode
    @classmethod
    def is_available(cls) -> bool:
        return is_demo_mode()
    @classmethod
    def get_default_config(cls) -> Dict[str, Any]:
        return {
            "sample_rate": 44100,
            "chunk_size": 1024,
        }
    @classmethod
    def enumerate_devices(cls) -> List[AudioDeviceInfo]:
        devices = []
        for idx, (name, is_loopback, channels, samplerate) in enumerate(_VIRTUAL_DEVICES):
            devices.append(AudioDeviceInfo(
                index=idx,
                name=name,
                is_input=True,
                is_loopback=is_loopback,
                channels=channels,
                default_samplerate=samplerate,
            ))
        logger.debug(f"Demo audio engine: {len(devices)} virtual device(s)")
        return devices
    @classmethod
    def create_stream(
        cls,
        device_index: int,
        is_loopback: bool,
        config: Dict[str, Any],
    ) -> DemoAudioCaptureStream:
        if device_index < 0 or device_index >= len(_VIRTUAL_DEVICES):
            raise ValueError(
                f"Invalid demo audio device index {device_index}. "
                f"Available: 0-{len(_VIRTUAL_DEVICES) - 1}"
            )
        merged = {**cls.get_default_config(), **config}
        return DemoAudioCaptureStream(device_index, is_loopback, merged)
--- a/server/src/wled_controller/core/audio/factory.py
+++ b/server/src/wled_controller/core/audio/factory.py
@@ -3,6 +3,7 @@
 from typing import Any, Dict, List, Optional, Type
 from wled_controller.core.audio.base import AudioCaptureEngine, AudioCaptureStreamBase
 from wled_controller.config import is_demo_mode
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
@@ -67,9 +68,13 @@ class AudioEngineRegistry:
        Returns:
            List of engine type identifiers that are available
        """
        demo = is_demo_mode()
        available = []
        for engine_type, engine_class in cls._engines.items():
            try:
                # In demo mode, only demo engines are available
                if demo and engine_type != "demo":
                    continue
                if engine_class.is_available():
                    available.append(engine_type)
            except Exception as e:
@@ -85,10 +90,13 @@ class AudioEngineRegistry:
        Returns:
            Engine type string, or None if no engines are available.
        """
        demo = is_demo_mode()
        best_type = None
        best_priority = -1
        for engine_type, engine_class in cls._engines.items():
            try:
                if demo and engine_type != "demo":
                    continue
                if engine_class.is_available() and engine_class.ENGINE_PRIORITY > best_priority:
                    best_priority = engine_class.ENGINE_PRIORITY
                    best_type = engine_type
@@ -102,9 +110,13 @@ class AudioEngineRegistry:
    def get_all_engines(cls) -> Dict[str, Type[AudioCaptureEngine]]:
        """Get all registered engines (available or not).
        In demo mode, only demo engines are returned.
        Returns:
            Dictionary mapping engine type to engine class
        """
        if is_demo_mode():
            return {k: v for k, v in cls._engines.items() if k == "demo"}
        return cls._engines.copy()
    @classmethod
--- a/server/src/wled_controller/core/automations/automation_engine.py
+++ b/server/src/wled_controller/core/automations/automation_engine.py
@@ -3,7 +3,7 @@
 import asyncio
 import re
 from datetime import datetime, timezone
-from typing import Dict, List, Optional, Set
+from typing import Dict, Optional, Set
 from wled_controller.core.automations.platform_detector import PlatformDetector
 from wled_controller.storage.automation import (
--- 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/calibration.py
+++ b/server/src/wled_controller/core/capture/calibration.py
@@ -1,7 +1,7 @@
 """Calibration system for mapping screen pixels to LED positions."""
 from dataclasses import dataclass, field
-from typing import Dict, List, Literal, Optional, Set, Tuple
+from typing import Dict, List, Literal, Set, Tuple
 import numpy as np
--- a/server/src/wled_controller/core/capture/screen_capture.py
+++ b/server/src/wled_controller/core/capture/screen_capture.py
@@ -1,7 +1,7 @@
 """Screen capture functionality using mss library."""
 from dataclasses import dataclass
-from typing import Dict, List
+from typing import List
 import mss
 import numpy as np
--- a/server/src/wled_controller/core/capture/screen_overlay.py
+++ b/server/src/wled_controller/core/capture/screen_overlay.py
@@ -1,12 +1,15 @@
 """Screen overlay visualization for LED calibration testing."""
 from __future__ import annotations
 import colorsys
 import logging
 import sys
 import threading
-import time
+from typing import TYPE_CHECKING, Dict, List, Optional
 if TYPE_CHECKING:
    import tkinter as tk
 from typing import Dict, List, Optional, Tuple
 from wled_controller.core.capture.calibration import CalibrationConfig
 from wled_controller.core.capture_engines.base import DisplayInfo
@@ -45,6 +48,8 @@ class OverlayWindow:
    def start(self, root: tk.Tk) -> None:
        """Create and show the overlay Toplevel (runs in Tk thread)."""
        import tkinter as tk  # lazy import — tkinter unavailable in headless CI
        self._window = tk.Toplevel(root)
        self._setup_window()
        self._draw_visualization()
@@ -75,6 +80,8 @@ class OverlayWindow:
        win.overrideredirect(True)
        win.attributes("-topmost", True)
        import tkinter as tk
        self._canvas = tk.Canvas(
            win,
            width=self.display_info.width,
@@ -271,6 +278,13 @@ class OverlayManager:
    def _start_tk_thread(self) -> None:
        def _run():
            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()
                self._tk_root.withdraw()  # invisible root — never shown
--- a/server/src/wled_controller/core/capture_engines/init.py
+++ b/server/src/wled_controller/core/capture_engines/init.py
@@ -13,6 +13,7 @@ from wled_controller.core.capture_engines.bettercam_engine import BetterCamEngin
 from wled_controller.core.capture_engines.wgc_engine import WGCEngine, WGCCaptureStream
 from wled_controller.core.capture_engines.scrcpy_engine import ScrcpyEngine, ScrcpyCaptureStream
 from wled_controller.core.capture_engines.camera_engine import CameraEngine, CameraCaptureStream
 from wled_controller.core.capture_engines.demo_engine import DemoCaptureEngine, DemoCaptureStream
 # Auto-register available engines
 EngineRegistry.register(MSSEngine)
@@ -21,6 +22,7 @@ EngineRegistry.register(BetterCamEngine)
 EngineRegistry.register(WGCEngine)
 EngineRegistry.register(ScrcpyEngine)
 EngineRegistry.register(CameraEngine)
 EngineRegistry.register(DemoCaptureEngine)
 __all__ = [
    "CaptureEngine",
@@ -40,4 +42,6 @@ __all__ = [
    "ScrcpyCaptureStream",
    "CameraEngine",
    "CameraCaptureStream",
    "DemoCaptureEngine",
    "DemoCaptureStream",
 ]
--- a/server/src/wled_controller/core/capture_engines/bettercam_engine.py
+++ b/server/src/wled_controller/core/capture_engines/bettercam_engine.py
@@ -4,7 +4,6 @@ import sys
 import time
 from typing import Any, Dict, List, Optional
 import numpy as np
 from wled_controller.core.capture_engines.base import (
    CaptureEngine,
@@ -145,9 +144,9 @@ class BetterCamEngine(CaptureEngine):
        if sys.platform != "win32":
            return False
        try:
-            import bettercam
+            import importlib.util
-            return True
+            return importlib.util.find_spec("bettercam") is not None
-        except ImportError:
+        except (ImportError, ModuleNotFoundError, ValueError):
            return False
    @classmethod
--- a/server/src/wled_controller/core/capture_engines/camera_engine.py
+++ b/server/src/wled_controller/core/capture_engines/camera_engine.py
@@ -14,7 +14,6 @@ import threading
 import time
 from typing import Any, Dict, List, Optional, Set
 import numpy as np
 from wled_controller.core.capture_engines.base import (
    CaptureEngine,
@@ -57,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.
+    On Windows, enumerates camera devices via the SetupAPI (pure ctypes,
-    Returns a dict mapping sequential index → friendly name.
+    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
+        import ctypes
-        c = wmi.WMI()
+        from ctypes import wintypes
-        cameras = c.query(
+
-            "SELECT Name FROM Win32_PnPEntity WHERE PNPClass = 'Camera'"
+        # ── 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/capture_engines/demo_engine.py
+++ b/server/src/wled_controller/core/capture_engines/demo_engine.py
@@ -0,0 +1,170 @@
 """Demo capture engine — virtual displays with animated test patterns."""
 import time
 from typing import Any, Dict, List, Optional
 import numpy as np
 from wled_controller.config import is_demo_mode
 from wled_controller.core.capture_engines.base import (
    CaptureEngine,
    CaptureStream,
    DisplayInfo,
    ScreenCapture,
 )
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 # Virtual display definitions: (name, width, height, x, y, is_primary)
 _VIRTUAL_DISPLAYS = [
    ("Demo Display 1080p", 1920, 1080, 0, 360, True),
    ("Demo Ultrawide", 3440, 1440, 1920, 0, False),
    ("Demo Portrait", 1080, 1920, 5360, 0, False),
 ]
 class DemoCaptureStream(CaptureStream):
    """Demo capture stream producing a radial rainbow centred on the screen.
    The rainbow rotates slowly over time — hue is mapped to the angle from
    the screen centre, and brightness fades toward the edges.
    """
    _RENDER_SCALE = 4  # render at 1/4 resolution, then upscale
    def __init__(self, display_index: int, config: Dict[str, Any]):
        super().__init__(display_index, config)
        self._width: int = config.get("width", 1920)
        self._height: int = config.get("height", 1080)
        # Pre-compute at render resolution
        rw = max(1, self._width // self._RENDER_SCALE)
        rh = max(1, self._height // self._RENDER_SCALE)
        self._rw = rw
        self._rh = rh
        # Coordinate grids centred at (0, 0), aspect-corrected so the
        # gradient is circular even on non-square displays
        aspect = self._width / max(self._height, 1)
        x = np.linspace(-aspect, aspect, rw, dtype=np.float32)
        y = np.linspace(-1.0, 1.0, rh, dtype=np.float32)
        self._yy, self._xx = np.meshgrid(y, x, indexing="ij")
        # Pre-compute angle (atan2) and radius — they don't change per frame
        self._angle = np.arctan2(self._yy, self._xx)  # -pi..pi
        self._radius = np.sqrt(self._xx ** 2 + self._yy ** 2)
    def initialize(self) -> None:
        self._initialized = True
        logger.info(
            f"Demo capture stream initialized "
            f"(display={self.display_index}, {self._width}x{self._height})"
        )
    def cleanup(self) -> None:
        self._initialized = False
        logger.info(f"Demo capture stream cleaned up (display={self.display_index})")
    def capture_frame(self) -> Optional[ScreenCapture]:
        if not self._initialized:
            self.initialize()
        t = time.time() % 1e6
        # Hue = angle from centre, rotating over time
        rotation = t * 0.15  # radians per second
        hue = ((self._angle + rotation) / (2.0 * np.pi)) % 1.0
        # Saturation: full
        # Value: bright at centre, fading toward edges
        max_r = float(self._radius.max()) or 1.0
        val = np.clip(1.0 - 0.6 * (self._radius / max_r), 0.0, 1.0)
        # Vectorised HSV → RGB (S=1 simplification)
        h6 = hue * 6.0
        sector = h6.astype(np.int32) % 6
        frac = h6 - np.floor(h6)
        q = val * (1.0 - frac)
        t_ch = val * frac  # "t" channel in HSV conversion
        r = np.where(sector == 0, val,
            np.where(sector == 1, q,
            np.where(sector == 2, 0,
            np.where(sector == 3, 0,
            np.where(sector == 4, t_ch, val)))))
        g = np.where(sector == 0, t_ch,
            np.where(sector == 1, val,
            np.where(sector == 2, val,
            np.where(sector == 3, q,
            np.where(sector == 4, 0, 0)))))
        b = np.where(sector == 0, 0,
            np.where(sector == 1, 0,
            np.where(sector == 2, t_ch,
            np.where(sector == 3, val,
            np.where(sector == 4, val, q)))))
        small_u8 = (np.stack([r, g, b], axis=-1) * 255.0).astype(np.uint8)
        # Upscale to full resolution
        if self._RENDER_SCALE > 1:
            image = np.repeat(
                np.repeat(small_u8, self._RENDER_SCALE, axis=0),
                self._RENDER_SCALE, axis=1,
            )[: self._height, : self._width]
        else:
            image = small_u8
        return ScreenCapture(
            image=image,
            width=self._width,
            height=self._height,
            display_index=self.display_index,
        )
 class DemoCaptureEngine(CaptureEngine):
    """Virtual capture engine for demo mode.
    Provides virtual displays and produces animated test-pattern frames
    so the full capture pipeline works without real monitors.
    """
    ENGINE_TYPE = "demo"
    ENGINE_PRIORITY = 1000  # Highest priority in demo mode
    @classmethod
    def is_available(cls) -> bool:
        return is_demo_mode()
    @classmethod
    def get_default_config(cls) -> Dict[str, Any]:
        return {}
    @classmethod
    def get_available_displays(cls) -> List[DisplayInfo]:
        displays = []
        for idx, (name, width, height, x, y, primary) in enumerate(_VIRTUAL_DISPLAYS):
            displays.append(DisplayInfo(
                index=idx,
                name=name,
                width=width,
                height=height,
                x=x,
                y=y,
                is_primary=primary,
                refresh_rate=60,
            ))
        logger.debug(f"Demo engine: {len(displays)} virtual display(s)")
        return displays
    @classmethod
    def create_stream(
        cls, display_index: int, config: Dict[str, Any],
    ) -> DemoCaptureStream:
        if display_index < 0 or display_index >= len(_VIRTUAL_DISPLAYS):
            raise ValueError(
                f"Invalid demo display index {display_index}. "
                f"Available: 0-{len(_VIRTUAL_DISPLAYS) - 1}"
            )
        name, width, height, *_ = _VIRTUAL_DISPLAYS[display_index]
        stream_config = {**config, "width": width, "height": height}
        return DemoCaptureStream(display_index, stream_config)
--- a/server/src/wled_controller/core/capture_engines/dxcam_engine.py
+++ b/server/src/wled_controller/core/capture_engines/dxcam_engine.py
@@ -4,7 +4,6 @@ import sys
 import time
 from typing import Any, Dict, List, Optional
 import numpy as np
 from wled_controller.core.capture_engines.base import (
    CaptureEngine,
@@ -145,9 +144,9 @@ class DXcamEngine(CaptureEngine):
        if sys.platform != "win32":
            return False
        try:
-            import dxcam
+            import importlib.util
-            return True
+            return importlib.util.find_spec("dxcam") is not None
-        except ImportError:
+        except (ImportError, ModuleNotFoundError, ValueError):
            return False
    @classmethod
--- a/server/src/wled_controller/core/capture_engines/factory.py
+++ b/server/src/wled_controller/core/capture_engines/factory.py
@@ -3,6 +3,7 @@
 from typing import Any, Dict, List, Optional, Type
 from wled_controller.core.capture_engines.base import CaptureEngine, CaptureStream
 from wled_controller.config import is_demo_mode
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
@@ -67,9 +68,13 @@ class EngineRegistry:
        Returns:
            List of engine type identifiers that are available
        """
        demo = is_demo_mode()
        available = []
        for engine_type, engine_class in cls._engines.items():
            try:
                # In demo mode, only demo engines are available
                if demo and engine_type != "demo":
                    continue
                if engine_class.is_available():
                    available.append(engine_type)
            except Exception as e:
@@ -86,10 +91,13 @@ class EngineRegistry:
        Returns:
            Engine type string, or None if no engines are available.
        """
        demo = is_demo_mode()
        best_type = None
        best_priority = -1
        for engine_type, engine_class in cls._engines.items():
            try:
                if demo and engine_type != "demo":
                    continue
                if engine_class.is_available() and engine_class.ENGINE_PRIORITY > best_priority:
                    best_priority = engine_class.ENGINE_PRIORITY
                    best_type = engine_type
@@ -103,9 +111,13 @@ class EngineRegistry:
    def get_all_engines(cls) -> Dict[str, Type[CaptureEngine]]:
        """Get all registered engines (available or not).
        In demo mode, only demo engines are returned.
        Returns:
            Dictionary mapping engine type to engine class
        """
        if is_demo_mode():
            return {k: v for k, v in cls._engines.items() if k == "demo"}
        return cls._engines.copy()
    @classmethod
--- a/server/src/wled_controller/core/capture_engines/mss_engine.py
+++ b/server/src/wled_controller/core/capture_engines/mss_engine.py
@@ -91,9 +91,9 @@ class MSSEngine(CaptureEngine):
    @classmethod
    def is_available(cls) -> bool:
        try:
-            import mss
+            import importlib.util
-            return True
+            return importlib.util.find_spec("mss") is not None
-        except ImportError:
+        except (ImportError, ModuleNotFoundError, ValueError):
            return False
    @classmethod
--- a/server/src/wled_controller/core/capture_engines/wgc_engine.py
+++ b/server/src/wled_controller/core/capture_engines/wgc_engine.py
@@ -5,7 +5,6 @@ import sys
 import threading
 from typing import Any, Dict, List, Optional
 import numpy as np
 from wled_controller.core.capture_engines.base import (
    CaptureEngine,
@@ -220,9 +219,9 @@ class WGCEngine(CaptureEngine):
            pass
        try:
-            import windows_capture
+            import importlib.util
-            return True
+            return importlib.util.find_spec("windows_capture") is not None
-        except ImportError:
+        except (ImportError, ModuleNotFoundError, ValueError):
            return False
    @classmethod
--- a/server/src/wled_controller/core/demo_seed.py
+++ b/server/src/wled_controller/core/demo_seed.py
@@ -0,0 +1,412 @@
 """Seed data generator for demo mode.
 Populates the demo data directory with sample entities on first run,
 giving new users a realistic out-of-the-box experience without needing
 real hardware.
 """
 import json
 from datetime import datetime, timezone
 from pathlib import Path
 from wled_controller.config import StorageConfig
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
 # Fixed IDs so cross-references are stable
 _DEVICE_IDS = {
    "strip": "device_demo0001",
    "matrix": "device_demo0002",
    "ring": "device_demo0003",
 }
 _TARGET_IDS = {
    "strip": "pt_demo0001",
    "matrix": "pt_demo0002",
 }
 _PS_IDS = {
    "main": "ps_demo0001",
    "secondary": "ps_demo0002",
 }
 _CSS_IDS = {
    "gradient": "css_demo0001",
    "cycle": "css_demo0002",
    "picture": "css_demo0003",
    "audio": "css_demo0004",
 }
 _AS_IDS = {
    "system": "as_demo0001",
    "mono": "as_demo0002",
 }
 _TPL_ID = "tpl_demo0001"
 _SCENE_ID = "scene_demo0001"
 _NOW = datetime.now(timezone.utc).isoformat()
 def _write_store(path: Path, json_key: str, items: dict) -> None:
    """Write a store JSON file with version wrapper."""
    path.parent.mkdir(parents=True, exist_ok=True)
    data = {
        "version": "1.0.0",
        json_key: items,
    }
    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
    logger.info(f"Seeded {len(items)} {json_key} -> {path}")
 def _has_data(storage_config: StorageConfig) -> bool:
    """Check if any demo store file already has entities."""
    for field_name in storage_config.model_fields:
        value = getattr(storage_config, field_name)
        if not isinstance(value, str):
            continue
        p = Path(value)
        if p.exists() and p.stat().st_size > 20:
            # File exists and is non-trivial — check if it has entities
            try:
                raw = json.loads(p.read_text(encoding="utf-8"))
                for key, val in raw.items():
                    if key != "version" and isinstance(val, dict) and val:
                        return True
            except Exception:
                pass
    return False
 def seed_demo_data(storage_config: StorageConfig) -> None:
    """Populate demo data directory with sample entities.
    Only runs when the demo data directory is empty (no existing entities).
    Must be called BEFORE store constructors run so they load the seeded data.
    """
    if _has_data(storage_config):
        logger.info("Demo data already exists — skipping seed")
        return
    logger.info("Seeding demo data for first-run experience")
    _seed_devices(Path(storage_config.devices_file))
    _seed_capture_templates(Path(storage_config.templates_file))
    _seed_output_targets(Path(storage_config.output_targets_file))
    _seed_picture_sources(Path(storage_config.picture_sources_file))
    _seed_color_strip_sources(Path(storage_config.color_strip_sources_file))
    _seed_audio_sources(Path(storage_config.audio_sources_file))
    _seed_scene_presets(Path(storage_config.scene_presets_file))
    logger.info("Demo seed data complete")
 # ── Devices ────────────────────────────────────────────────────────
 def _seed_devices(path: Path) -> None:
    devices = {
        _DEVICE_IDS["strip"]: {
            "id": _DEVICE_IDS["strip"],
            "name": "Demo LED Strip",
            "url": "demo://demo-strip",
            "led_count": 60,
            "enabled": True,
            "device_type": "demo",
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _DEVICE_IDS["matrix"]: {
            "id": _DEVICE_IDS["matrix"],
            "name": "Demo LED Matrix",
            "url": "demo://demo-matrix",
            "led_count": 256,
            "enabled": True,
            "device_type": "demo",
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _DEVICE_IDS["ring"]: {
            "id": _DEVICE_IDS["ring"],
            "name": "Demo LED Ring",
            "url": "demo://demo-ring",
            "led_count": 24,
            "enabled": True,
            "device_type": "demo",
            "created_at": _NOW,
            "updated_at": _NOW,
        },
    }
    _write_store(path, "devices", devices)
 # ── Capture Templates ──────────────────────────────────────────────
 def _seed_capture_templates(path: Path) -> None:
    templates = {
        _TPL_ID: {
            "id": _TPL_ID,
            "name": "Demo Capture",
            "engine_type": "demo",
            "engine_config": {},
            "description": "Default capture template using demo engine",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
        },
    }
    _write_store(path, "templates", templates)
 # ── Output Targets ─────────────────────────────────────────────────
 def _seed_output_targets(path: Path) -> None:
    targets = {
        _TARGET_IDS["strip"]: {
            "id": _TARGET_IDS["strip"],
            "name": "Strip — Gradient",
            "target_type": "led",
            "device_id": _DEVICE_IDS["strip"],
            "color_strip_source_id": _CSS_IDS["gradient"],
            "brightness_value_source_id": "",
            "fps": 30,
            "keepalive_interval": 1.0,
            "state_check_interval": 30,
            "min_brightness_threshold": 0,
            "adaptive_fps": False,
            "protocol": "ddp",
            "description": "Demo LED strip with gradient effect",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _TARGET_IDS["matrix"]: {
            "id": _TARGET_IDS["matrix"],
            "name": "Matrix — Screen Capture",
            "target_type": "led",
            "device_id": _DEVICE_IDS["matrix"],
            "color_strip_source_id": _CSS_IDS["picture"],
            "brightness_value_source_id": "",
            "fps": 30,
            "keepalive_interval": 1.0,
            "state_check_interval": 30,
            "min_brightness_threshold": 0,
            "adaptive_fps": False,
            "protocol": "ddp",
            "description": "Demo LED matrix with screen capture",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
        },
    }
    _write_store(path, "output_targets", targets)
 # ── Picture Sources ────────────────────────────────────────────────
 def _seed_picture_sources(path: Path) -> None:
    sources = {
        _PS_IDS["main"]: {
            "id": _PS_IDS["main"],
            "name": "Demo Display 1080p",
            "stream_type": "raw",
            "display_index": 0,
            "capture_template_id": _TPL_ID,
            "target_fps": 30,
            "description": "Virtual 1920x1080 display capture",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
            # Nulls for non-applicable subclass fields
            "source_stream_id": None,
            "postprocessing_template_id": None,
            "image_source": None,
            "url": None,
            "loop": None,
            "playback_speed": None,
            "start_time": None,
            "end_time": None,
            "resolution_limit": None,
            "clock_id": None,
        },
        _PS_IDS["secondary"]: {
            "id": _PS_IDS["secondary"],
            "name": "Demo Display 4K",
            "stream_type": "raw",
            "display_index": 1,
            "capture_template_id": _TPL_ID,
            "target_fps": 30,
            "description": "Virtual 3840x2160 display capture",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
            "source_stream_id": None,
            "postprocessing_template_id": None,
            "image_source": None,
            "url": None,
            "loop": None,
            "playback_speed": None,
            "start_time": None,
            "end_time": None,
            "resolution_limit": None,
            "clock_id": None,
        },
    }
    _write_store(path, "picture_sources", sources)
 # ── Color Strip Sources ────────────────────────────────────────────
 def _seed_color_strip_sources(path: Path) -> None:
    sources = {
        _CSS_IDS["gradient"]: {
            "id": _CSS_IDS["gradient"],
            "name": "Rainbow Gradient",
            "source_type": "gradient",
            "description": "Smooth rainbow gradient across all LEDs",
            "clock_id": None,
            "tags": ["demo"],
            "stops": [
                {"position": 0.0, "color": [255, 0, 0]},
                {"position": 0.25, "color": [255, 255, 0]},
                {"position": 0.5, "color": [0, 255, 0]},
                {"position": 0.75, "color": [0, 0, 255]},
                {"position": 1.0, "color": [255, 0, 255]},
            ],
            "animation": {"enabled": True, "type": "gradient_shift", "speed": 0.5},
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _CSS_IDS["cycle"]: {
            "id": _CSS_IDS["cycle"],
            "name": "Warm Color Cycle",
            "source_type": "color_cycle",
            "description": "Smoothly cycles through warm colors",
            "clock_id": None,
            "tags": ["demo"],
            "colors": [
                [255, 60, 0],
                [255, 140, 0],
                [255, 200, 50],
                [255, 100, 20],
            ],
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _CSS_IDS["picture"]: {
            "id": _CSS_IDS["picture"],
            "name": "Screen Capture — Main Display",
            "source_type": "picture",
            "description": "Captures colors from the main demo display",
            "clock_id": None,
            "tags": ["demo"],
            "picture_source_id": _PS_IDS["main"],
            "fps": 30,
            "smoothing": 0.3,
            "interpolation_mode": "average",
            "calibration": {
                "mode": "simple",
                "layout": "clockwise",
                "start_position": "bottom_left",
                "leds_top": 28,
                "leds_bottom": 28,
                "leds_left": 16,
                "leds_right": 16,
            },
            "led_count": 0,
            "created_at": _NOW,
            "updated_at": _NOW,
        },
        _CSS_IDS["audio"]: {
            "id": _CSS_IDS["audio"],
            "name": "Audio Spectrum",
            "source_type": "audio",
            "description": "Audio-reactive spectrum visualization",
            "clock_id": None,
            "tags": ["demo"],
            "visualization_mode": "spectrum",
            "audio_source_id": _AS_IDS["mono"],
            "sensitivity": 1.0,
            "smoothing": 0.3,
            "palette": "rainbow",
            "color": [0, 255, 0],
            "color_peak": [255, 0, 0],
            "led_count": 0,
            "mirror": False,
            "created_at": _NOW,
            "updated_at": _NOW,
        },
    }
    _write_store(path, "color_strip_sources", sources)
 # ── Audio Sources ──────────────────────────────────────────────────
 def _seed_audio_sources(path: Path) -> None:
    sources = {
        _AS_IDS["system"]: {
            "id": _AS_IDS["system"],
            "name": "Demo System Audio",
            "source_type": "multichannel",
            "device_index": 1,
            "is_loopback": True,
            "audio_template_id": None,
            "description": "Virtual system audio (loopback)",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
            # Forward-compat null fields
            "audio_source_id": None,
            "channel": None,
        },
        _AS_IDS["mono"]: {
            "id": _AS_IDS["mono"],
            "name": "Demo Audio — Mono",
            "source_type": "mono",
            "audio_source_id": _AS_IDS["system"],
            "channel": "mono",
            "description": "Mono mix of demo system audio",
            "tags": ["demo"],
            "created_at": _NOW,
            "updated_at": _NOW,
            # Forward-compat null fields
            "device_index": None,
            "is_loopback": None,
            "audio_template_id": None,
        },
    }
    _write_store(path, "audio_sources", sources)
 # ── Scene Presets ──────────────────────────────────────────────────
 def _seed_scene_presets(path: Path) -> None:
    presets = {
        _SCENE_ID: {
            "id": _SCENE_ID,
            "name": "Demo Ambient",
            "description": "Activates gradient on the strip and screen capture on the matrix",
            "tags": ["demo"],
            "order": 0,
            "targets": [
                {
                    "target_id": _TARGET_IDS["strip"],
                    "running": True,
                    "color_strip_source_id": _CSS_IDS["gradient"],
                    "brightness_value_source_id": "",
                    "fps": 30,
                },
                {
                    "target_id": _TARGET_IDS["matrix"],
                    "running": True,
                    "color_strip_source_id": _CSS_IDS["picture"],
                    "brightness_value_source_id": "",
                    "fps": 30,
                },
            ],
            "created_at": _NOW,
            "updated_at": _NOW,
        },
    }
    _write_store(path, "scene_presets", presets)
--- a/server/src/wled_controller/core/devices/adalight_client.py
+++ b/server/src/wled_controller/core/devices/adalight_client.py
@@ -2,7 +2,7 @@
 import asyncio
 from datetime import datetime, timezone
-from typing import List, Optional, Tuple
+from typing import Optional, Tuple
 import numpy as np
--- a/server/src/wled_controller/core/devices/chroma_client.py
+++ b/server/src/wled_controller/core/devices/chroma_client.py
@@ -1,7 +1,6 @@
 """Razer Chroma SDK LED client — controls Razer RGB peripherals via REST API."""
 import asyncio
 import json
 from datetime import datetime, timezone
 from typing import List, Optional, Tuple, Union
--- a/server/src/wled_controller/core/devices/chroma_provider.py
+++ b/server/src/wled_controller/core/devices/chroma_provider.py
@@ -1,6 +1,5 @@
 """Razer Chroma SDK device provider — control Razer RGB peripherals."""
 from datetime import datetime, timezone
 from typing import List
 from wled_controller.core.devices.led_client import (
--- a/server/src/wled_controller/core/devices/demo_provider.py
+++ b/server/src/wled_controller/core/devices/demo_provider.py
@@ -0,0 +1,93 @@
 """Demo device provider — virtual LED devices for demo mode."""
 from datetime import datetime, timezone
 from typing import List
 from wled_controller.config import is_demo_mode
 from wled_controller.core.devices.led_client import (
    DeviceHealth,
    DiscoveredDevice,
    LEDClient,
    LEDDeviceProvider,
 )
 from wled_controller.core.devices.mock_client import MockClient
 # Pre-defined virtual devices: (name, led_count, ip, width, height)
 _DEMO_DEVICES = [
    ("Demo LED Strip", 60, "demo-strip", None, None),
    ("Demo LED Matrix", 256, "demo-matrix", 16, 16),
    ("Demo LED Ring", 24, "demo-ring", None, None),
 ]
 class DemoDeviceProvider(LEDDeviceProvider):
    """Provider for virtual demo LED devices.
    Exposes three discoverable virtual devices when demo mode is active.
    Uses MockClient for actual LED output (pixels are silently discarded).
    """
    @property
    def device_type(self) -> str:
        return "demo"
    @property
    def capabilities(self) -> set:
        return {"manual_led_count", "power_control", "brightness_control", "static_color"}
    def create_client(self, url: str, **kwargs) -> LEDClient:
        return MockClient(
            url,
            led_count=kwargs.get("led_count", 0),
            send_latency_ms=kwargs.get("send_latency_ms", 0),
        )
    async def check_health(self, url: str, http_client, prev_health=None) -> DeviceHealth:
        # Simulate ~2ms latency for realistic appearance
        return DeviceHealth(
            online=True,
            latency_ms=2.0,
            last_checked=datetime.now(timezone.utc),
            device_name=url,
            device_version="demo",
        )
    async def validate_device(self, url: str) -> dict:
        # Look up configured LED count from demo devices
        for name, led_count, ip, _w, _h in _DEMO_DEVICES:
            if url == f"demo://{ip}":
                return {"led_count": led_count}
        # Fallback for unknown demo URLs
        return {"led_count": 60}
    async def discover(self, timeout: float = 3.0) -> List[DiscoveredDevice]:
        if not is_demo_mode():
            return []
        return [
            DiscoveredDevice(
                name=name,
                url=f"demo://{ip}",
                device_type="demo",
                ip=ip,
                mac=f"DE:MO:00:00:00:{i:02X}",
                led_count=led_count,
                version="demo",
            )
            for i, (name, led_count, ip, _w, _h) in enumerate(_DEMO_DEVICES)
        ]
    async def get_power(self, url: str, **kwargs) -> bool:
        return True
    async def set_power(self, url: str, on: bool, **kwargs) -> None:
        pass
    async def get_brightness(self, url: str) -> int:
        return 255
    async def set_brightness(self, url: str, brightness: int) -> None:
        pass
    async def set_color(self, url: str, color, **kwargs) -> None:
        pass
--- a/server/src/wled_controller/core/devices/dmx_client.py
+++ b/server/src/wled_controller/core/devices/dmx_client.py
@@ -7,7 +7,7 @@ from typing import List, Optional, Tuple, Union
 import numpy as np
-from wled_controller.core.devices.led_client import LEDClient, DeviceHealth
+from wled_controller.core.devices.led_client import LEDClient
 from wled_controller.utils import get_logger
 logger = get_logger(__name__)
--- a/server/src/wled_controller/core/devices/espnow_provider.py
+++ b/server/src/wled_controller/core/devices/espnow_provider.py
@@ -1,6 +1,5 @@
 """ESP-NOW device provider — ultra-low-latency LED control via ESP32 gateway."""
 from datetime import datetime, timezone
 from typing import List
 from wled_controller.core.devices.led_client import (
--- a/server/src/wled_controller/core/devices/gamesense_client.py
+++ b/server/src/wled_controller/core/devices/gamesense_client.py
@@ -1,6 +1,5 @@
 """SteelSeries GameSense LED client — controls SteelSeries RGB peripherals via REST API."""
 import asyncio
 import json
 import os
 import platform
--- a/server/src/wled_controller/core/devices/gamesense_provider.py
+++ b/server/src/wled_controller/core/devices/gamesense_provider.py
@@ -1,6 +1,5 @@
 """SteelSeries GameSense device provider — control SteelSeries RGB peripherals."""
 from datetime import datetime, timezone
 from typing import List
 from wled_controller.core.devices.led_client import (
--- a/server/src/wled_controller/core/devices/hue_provider.py
+++ b/server/src/wled_controller/core/devices/hue_provider.py
@@ -1,7 +1,6 @@
 """Philips Hue device provider — entertainment streaming to Hue lights."""
 import asyncio
 from datetime import datetime, timezone
 from typing import List, Tuple
 from wled_controller.core.devices.led_client import (
--- a/server/src/wled_controller/core/devices/led_client.py
+++ b/server/src/wled_controller/core/devices/led_client.py
@@ -1,7 +1,7 @@
 """Abstract base class for LED device communication clients and provider registry."""
 from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Dict, List, Optional, Tuple, Union
@@ -317,5 +317,8 @@ def _register_builtin_providers():
    from wled_controller.core.devices.gamesense_provider import GameSenseDeviceProvider
    register_provider(GameSenseDeviceProvider())
    from wled_controller.core.devices.demo_provider import DemoDeviceProvider
    register_provider(DemoDeviceProvider())
 _register_builtin_providers()
--- a/server/src/wled_controller/core/devices/mqtt_client.py
+++ b/server/src/wled_controller/core/devices/mqtt_client.py
@@ -1,7 +1,7 @@
 """MQTT LED client — publishes pixel data to an MQTT topic."""
 import json
-from typing import List, Optional, Tuple, Union
+from typing import List, Tuple, Union
 import numpy as np
--- a/server/src/wled_controller/core/devices/mqtt_provider.py
+++ b/server/src/wled_controller/core/devices/mqtt_provider.py
@@ -1,7 +1,6 @@
 """MQTT device provider — factory, validation, health checks."""
-from datetime import datetime
+from typing import List
 from typing import List, Optional, Tuple
 from wled_controller.core.devices.led_client import (
    DeviceHealth,
@@ -11,7 +10,6 @@ from wled_controller.core.devices.led_client import (
 )
 from wled_controller.core.devices.mqtt_client import (
    MQTTLEDClient,
    get_mqtt_service,
    parse_mqtt_url,
 )
 from wled_controller.utils import get_logger
--- a/server/src/wled_controller/core/devices/openrgb_client.py
+++ b/server/src/wled_controller/core/devices/openrgb_client.py
@@ -5,7 +5,7 @@ import socket
 import struct
 import threading
 from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, List, Optional, Tuple, Union
 import numpy as np
@@ -165,7 +165,6 @@ class OpenRGBLEDClient(LEDClient):
    def _connect_sync(self) -> Tuple[Any, Any]:
        """Synchronous connect — runs in thread pool."""
        from openrgb import OpenRGBClient
        from openrgb.utils import DeviceType
        client = OpenRGBClient(self._host, self._port, name="WLED Controller")
        devices = client.devices
--- a/server/src/wled_controller/core/devices/openrgb_provider.py
+++ b/server/src/wled_controller/core/devices/openrgb_provider.py
@@ -1,7 +1,7 @@
 """OpenRGB device provider — factory, validation, health checks, discovery."""
 import asyncio
-from typing import List, Optional, Tuple
+from typing import List, Tuple
 from wled_controller.core.devices.led_client import (
    DeviceHealth,
--- a/server/src/wled_controller/core/devices/serial_provider.py
+++ b/server/src/wled_controller/core/devices/serial_provider.py
@@ -12,7 +12,6 @@ import numpy as np
 from wled_controller.core.devices.led_client import (
    DeviceHealth,
    DiscoveredDevice,
    LEDClient,
    LEDDeviceProvider,
 )
 from wled_controller.utils import get_logger
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
alexei.dolgolyov	5c814a64a7	fix: remove extraneous f-string prefixes in startup banner All checks were successful Lint & Test / test (push) Successful in 35s Details	2026-03-22 13:53:30 +03:00
alexei.dolgolyov	0716d602e2	docs: add CI/CD context file and pre-commit lint rule Some checks failed Lint & Test / test (push) Failing after 13s Details Create contexts/ci-cd.md documenting release pipeline, build scripts, CI runners, and versioning. Reference it from CLAUDE.md context table. Add mandatory pre-commit lint check rule to CLAUDE.md.	2026-03-22 13:52:47 +03:00
alexei.dolgolyov	42bc05c968	fix: update release description to match current build artifacts Some checks failed Lint & Test / test (push) Failing after 14s Details Add Windows installer, Docker volume mount, and first-time setup instructions to the Gitea release body. Fix Docker registry URL. Add CI/Release sync rule to CLAUDE.md.	2026-03-22 13:50:46 +03:00
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
alexei.dolgolyov	eeb51fa4e7	fix: skip display-dependent tests on headless CI Some checks failed Lint & Test / test (push) Successful in 1m52s Details Build Release / build-windows (push) Has been cancelled Details Tests that call get_available_displays() or capture_display() require a real display ($DISPLAY on Linux, always available on Windows/macOS). Mark them with @requires_display to skip on headless CI instead of failing with "$DISPLAY not set". Affects: test_screen_capture.py (4 tests), test_api.py (1 test).	2026-03-22 02:27:04 +03:00
alexei.dolgolyov	250ebcd105	fix: resolve all CI test failures — lazy tkinter, mock network calls Some checks failed Lint & Test / test (push) Failing after 1m54s Details - Lazy-import tkinter in screen_overlay.py (TYPE_CHECKING + runtime import) so the module loads on headless Linux CI without libtk8.6 - Fix test_wled_client.py: mock all HTTP endpoints with respx (info, cfg, state) instead of hitting real network - Fix test_calibration.py: assert numpy array shape instead of tuple - Fix test_processor_manager.py: update to current API (async remove_device, dict settings, no update_calibration) - Fix test_screen_capture.py: get_edge_segments allows more segments than pixels 341 tests passing, 0 failures.	2026-03-22 02:18:53 +03:00
alexei.dolgolyov	93943dc1fa	fix: lazy-import tkinter to fix CI on headless Linux Some checks failed Lint & Test / test (push) Failing after 2m16s Details screen_overlay.py imported tkinter at module level, which cascaded through processor_manager → every test touching the app on CI where libtk8.6.so is unavailable. Move to TYPE_CHECKING + runtime lazy import so the overlay module loads cleanly on headless systems. Also fix test_processor_manager.py to use ProcessorDependencies().	2026-03-22 02:01:54 +03:00
alexei.dolgolyov	34f142ee61	fix: add opencv-python-headless to dev deps and libportaudio2 to CI Some checks failed Lint & Test / test (push) Failing after 21s Details The test import chain (conftest → storage → filters → cv2) requires opencv-python-headless. Also install libportaudio2 for sounddevice.	2026-03-22 01:32:52 +03:00
alexei.dolgolyov	7380b33b9b	fix: resolve all 153 ruff lint errors for CI Some checks failed Lint & Test / test (push) Failing after 9s Details Auto-fixed 138 unused imports and f-string issues. Manually fixed: ambiguous variable names (l→layer), availability-check imports using importlib.util.find_spec, unused Color import, ImagePool forward ref via TYPE_CHECKING, multi-statement semicolons, and E402 suppression.	2026-03-22 01:29:26 +03:00
alexei.dolgolyov	f2871319cb	refactor: comprehensive code quality, security, and release readiness improvements Some checks failed Lint & Test / test (push) Failing after 48s Details Security: tighten CORS defaults, add webhook rate limiting, fix XSS in automations, guard WebSocket JSON.parse, validate ADB address input, seal debug exception leak, URL-encode WS tokens, CSS.escape in selectors. Code quality: add Pydantic models for brightness/power endpoints, fix thread safety and name uniqueness in DeviceStore, immutable update pattern, split 6 oversized files into 16 focused modules, enable TypeScript strictNullChecks (741→102 errors), type state variables, add dom-utils helper, migrate 3 modules from inline onclick to event delegation, ProcessorDependencies dataclass. Performance: async store saves, health endpoint log level, command palette debounce, optimized entity-events comparison, fix service worker precache list. Testing: expand from 45 to 293 passing tests — add store tests (141), route tests (25), core logic tests (42), E2E flow tests (33), organize into tests/api/, tests/storage/, tests/core/, tests/e2e/. DevOps: CI test pipeline, pre-commit config, Dockerfile multi-stage build with non-root user and health check, docker-compose improvements, version bump to 0.2.0. Docs: rewrite CLAUDE.md (202→56 lines), server/CLAUDE.md (212→76), create contexts/server-operations.md, fix .js→.ts references, fix env var prefix in README, rewrite INSTALLATION.md, add CONTRIBUTING.md and .env.example.	2026-03-22 00:38:28 +03:00
alexei.dolgolyov	07bb89e9b7	Refactor process picker into palette pattern, add notification app picker - Refactor process-picker.ts into generic NamePalette with two concrete instances: ProcessPalette (running processes) and NotificationAppPalette (OS notification history apps) - Notification color strip app colors and filter list now use NotificationAppPalette (shows display names like "Telegram" instead of process names like "telegram.exe") - Fix case-insensitive matching for app_colors and app_filter_list in notification_stream.py - Compact browse/remove buttons in notification app color rows with proper search icon - Remove old inline process-picker HTML/CSS (replaced by palette overlay) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-21 01:23:08 +03:00
alexei.dolgolyov	5fa851618b	Merge feature/demo-mode: virtual hardware sandbox for testing	2026-03-20 16:17:23 +03:00
alexei.dolgolyov	2240471b67	Add demo mode: virtual hardware sandbox for testing without real devices Demo mode provides a complete sandbox environment with: - Virtual capture engine (radial rainbow test pattern on 3 displays) - Virtual audio engine (synthetic music-like audio on 2 devices) - Virtual LED device provider (strip/60, matrix/256, ring/24 LEDs) - Isolated data directory (data/demo/) with auto-seeded sample entities - Dedicated config (config/demo_config.yaml) with pre-configured API key - Frontend indicator (DEMO badge + dismissible banner) - Engine filtering (only demo engines visible in demo mode) - Separate entry point: python -m wled_controller.demo (port 8081) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-20 16:17:14 +03:00
alexei.dolgolyov	81b275979b	Fix stale frame in API CSS preview when source is inactive Server: send initial frame immediately after metadata for api_input sources so the client gets the current buffer (fallback color if inactive) instead of never receiving a frame when push_generation stays at 0. Frontend: clear all test modal canvases on open to prevent stale pixels from previous sessions. Reset FPS timestamps after metadata so the initial bootstrap frame isn't counted in the FPS chart. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-20 14:29:51 +03:00
alexei.dolgolyov	47c696bae3	Frontend improvements: CSS foundations, accessibility, UX enhancements CSS: Add design token variables (spacing, timing, weights, z-index layers), migrate all hardcoded z-index to named vars, fix light theme contrast for WCAG AA, add skeleton loading cards, mask-composite fallback, card padding. Accessibility: aria-live on toast, aria-label on health dots, sr-only class, graph container keyboard focusable, MQTT password wrapped in form element. UX: Modal auto-focus on open, inline field validation with blur, undo toast with countdown, bulk action progress indicator, API error toast on failure. i18n: Add common.undo, validation.required, bulk.processing, api.error.* keys in EN/RU/ZH. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-20 01:51:22 +03:00
alexei.dolgolyov	43fbc1eff5	Fix modal-open layout shift caused by position:fixed scroll lock Replace the body position:fixed hack with overflow:hidden on html element, which works cleanly with scrollbar-gutter:stable to prevent layout shift. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-19 22:37:10 +03:00
alexei.dolgolyov	997ff2fd70	Migrate frontend from JavaScript to TypeScript - Rename all 54 .js files to .ts, update esbuild entry point - Add tsconfig.json, TypeScript devDependency, typecheck script - Create types.ts with 25+ interfaces matching backend Pydantic schemas (Device, OutputTarget, ColorStripSource, PatternTemplate, ValueSource, AudioSource, PictureSource, ScenePreset, SyncClock, Automation, etc.) - Make DataCache generic (DataCache<T>) with typed state instances - Type all state variables in state.ts with proper entity types - Type all create*Card functions with proper entity interfaces - Type all function parameters and return types across all 54 files - Type core component constructors (CardSection, IconSelect, EntitySelect, FilterList, TagInput, TreeNav, Modal) with exported option interfaces - Add comprehensive global.d.ts for window function declarations - Type fetchWithAuth with FetchAuthOpts interface - Remove all (window as any) casts in favor of global.d.ts declarations - Zero tsc errors, esbuild bundle unchanged Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-19 13:08:23 +03:00
alexei.dolgolyov	55772b58dd	Replace deploy workflow with portable Windows release build - Remove old Docker-based deploy.yml - Add release.yml: builds portable ZIP on tag push, uploads to Gitea - Add build-dist.ps1: downloads embedded Python, installs deps, bundles app - Add scrollbar-gutter: stable to prevent layout shift Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-19 11:21:55 +03:00
alexei.dolgolyov	968046d96b	HA integration: fix reload loop, parallel device fetch, WS guards, translations - Fix indentation bug causing scenes device to not register - Use nonlocal tracking to prevent infinite reload loops on target/scene changes - Guard WS start/stop to avoid redundant connections - Parallel device brightness fetching via asyncio.gather - Route set_leds service to correct coordinator by source ID - Remove stale pattern cache, reuse single timeout object - Fix translations structure for light/select entities - Unregister service when last config entry unloaded Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-19 11:21:46 +03:00