chore: release v0.7.0

Database opened its sqlite3 connection eagerly in __init__ and closed it
in close(); the lifespan called close() on shutdown. In production this
is fine — the lifespan runs once per process. Under pytest the module-
level ``db`` singleton survives across every TestClient session, so the
second test file's lifespan startup hit
``sqlite3.ProgrammingError: Cannot operate on a closed database`` at
fixture-setup time (AutoBackupEngine.__init__ → db.get_setting("…")
was the first reader). 65 spurious "errors" on a full Windows pytest run.

- Database: extract _open() from __init__, add ensure_open() that
  reopens iff _conn is None, and have close() null _conn after the
  TRUNCATE checkpoint so re-close is idempotent.
- main.py lifespan startup: call db.ensure_open() before any setting
  read, so subsequent TestClient sessions get a live connection.
- tests/storage/test_database_reopen.py: pin the four invariants —
  close→ensure_open round-trips data, ensure_open is a no-op when
  open, close is idempotent, and using the DB after close without
  ensure_open raises (callers must opt in).

Full backend suite: 1551 pass / 1 skip / 0 errors. Ruff clean.

.gitea/workflows/build-android.yml

@@ -0,0 +1,248 @@
+name: Build Android APK
+
+on:
+  # Release tags only — building the ~100 MB APK on every master push
+  # burned Gitea runner minutes without producing a useful artifact.
+  # Use workflow_dispatch for on-demand dev builds.
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label (e.g. dev, 0.3.0-test)'
+        required: false
+        default: 'dev'
+
+jobs:
+  build-android:
+    runs-on: ubuntu-latest
+    env:
+      JAVA_VERSION: '17'
+      PYTHON_VERSION: '3.11'
+      ANDROID_CMDLINE_TOOLS_VERSION: '11076708'
+      ANDROID_SDK_PLATFORM: 'android-34'
+      ANDROID_BUILD_TOOLS: '34.0.0'
+      ANDROID_NDK_VERSION: '26.1.10909125'
+      # Surfaced at job level (not step level) so the `if: env.X != ''`
+      # check on the Decode step actually sees it — step-level env is
+      # NOT available in that step's own `if:` expression, which
+      # silently skipped the decode and produced debug-signed release
+      # APKs until it was noticed.
+      ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve build label
+        id: label
+        run: |
+          REF="${{ gitea.ref_name }}"
+          if echo "$REF" | grep -qE '^v[0-9]'; then
+            LABEL="${REF#v}"
+            IS_RELEASE="true"
+          elif [ -n "${{ inputs.version }}" ]; then
+            LABEL="${{ inputs.version }}"
+            IS_RELEASE="false"
+          else
+            LABEL="dev-${{ gitea.sha }}"
+            IS_RELEASE="false"
+          fi
+          LABEL="${LABEL:0:40}"
+          echo "label=$LABEL" >> "$GITHUB_OUTPUT"
+          echo "is_release=$IS_RELEASE" >> "$GITHUB_OUTPUT"
+          echo "Build label: $LABEL (release=$IS_RELEASE)"
+
+      - name: Guard release tag against missing keystore
+        # Release tags MUST produce a release-signed APK, otherwise existing
+        # installs can't upgrade (signature mismatch). Fail loudly instead
+        # of silently falling back to the debug signing config.
+        # Runs before JDK/Python/SDK/NDK setup so a misconfigured release
+        # tag fails in seconds instead of after several minutes of setup.
+        if: ${{ steps.label.outputs.is_release == 'true' && env.ANDROID_KEYSTORE_BASE64 == '' }}
+        run: |
+          echo "::error::Release tag ${{ gitea.ref_name }} requires ANDROID_KEYSTORE_BASE64 (plus KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD) to be configured in Gitea → Settings → Secrets."
+          exit 1
+
+      - name: Setup JDK ${{ env.JAVA_VERSION }}
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ env.JAVA_VERSION }}
+
+      - name: Setup Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Setup Android SDK + NDK
+        run: |
+          set -euo pipefail
+          SDK_ROOT="$HOME/android-sdk"
+          mkdir -p "$SDK_ROOT/cmdline-tools"
+          cd "$SDK_ROOT/cmdline-tools"
+          curl -sSL --retry 3 \
+            -o cmdline-tools.zip \
+            "https://dl.google.com/android/repository/commandlinetools-linux-${ANDROID_CMDLINE_TOOLS_VERSION}_latest.zip"
+          unzip -q cmdline-tools.zip
+          rm cmdline-tools.zip
+          mv cmdline-tools latest
+
+          export ANDROID_SDK_ROOT="$SDK_ROOT"
+          export ANDROID_HOME="$SDK_ROOT"
+          SDKMANAGER="$SDK_ROOT/cmdline-tools/latest/bin/sdkmanager"
+
+          yes | "$SDKMANAGER" --licenses > /dev/null 2>&1 || true
+          "$SDKMANAGER" --install \
+            "platform-tools" \
+            "platforms;${ANDROID_SDK_PLATFORM}" \
+            "build-tools;${ANDROID_BUILD_TOOLS}" \
+            "ndk;${ANDROID_NDK_VERSION}" > /dev/null
+
+          echo "ANDROID_SDK_ROOT=$SDK_ROOT" >> "$GITHUB_ENV"
+          echo "ANDROID_HOME=$SDK_ROOT" >> "$GITHUB_ENV"
+          echo "ANDROID_NDK_HOME=$SDK_ROOT/ndk/${ANDROID_NDK_VERSION}" >> "$GITHUB_ENV"
+          echo "$SDK_ROOT/platform-tools" >> "$GITHUB_PATH"
+          echo "$SDK_ROOT/cmdline-tools/latest/bin" >> "$GITHUB_PATH"
+
+      - name: Create local.properties
+        run: |
+          echo "sdk.dir=$ANDROID_SDK_ROOT" > android/local.properties
+
+      - name: Link Python source (junction equivalent)
+        run: |
+          set -euo pipefail
+          # Chaquopy reads Python modules from android/app/src/main/python/
+          # On Windows dev machines this is a directory junction; on Linux
+          # CI use a symlink. The parent dir is .gitignore'd (the junction
+          # target is the real content), so we have to create it first.
+          mkdir -p android/app/src/main/python
+          ln -sfn "$(pwd)/server/src/ledgrab" android/app/src/main/python/ledgrab
+          ls -la android/app/src/main/python/
+          # Sanity check — readlink resolves the link and the directory exists.
+          test -d android/app/src/main/python/ledgrab
+
+      - name: Decode signing keystore
+        id: keystore
+        if: env.ANDROID_KEYSTORE_BASE64 != ''
+        run: |
+          set -euo pipefail
+          mkdir -p android/keystore
+          echo "$ANDROID_KEYSTORE_BASE64" | base64 -d > android/keystore/release.jks
+          echo "path=$(pwd)/android/keystore/release.jks" >> "$GITHUB_OUTPUT"
+          echo "present=true" >> "$GITHUB_OUTPUT"
+
+      - name: Build APK
+        working-directory: android
+        env:
+          ANDROID_KEYSTORE_PATH: ${{ steps.keystore.outputs.path }}
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: |
+          chmod +x gradlew
+          if [ "${{ steps.keystore.outputs.present }}" = "true" ] && [ "${{ steps.label.outputs.is_release }}" = "true" ]; then
+            echo "Building signed release APK"
+            ./gradlew --no-daemon assembleRelease
+          else
+            echo "Building debug APK (no signing keystore available or not a release tag)"
+            ./gradlew --no-daemon assembleDebug
+          fi
+
+      - name: Locate and rename APK
+        id: apk
+        run: |
+          set -euo pipefail
+          SRC=$(ls android/app/build/outputs/apk/release/*.apk 2>/dev/null | head -1 || true)
+          if [ -z "$SRC" ]; then
+            SRC=$(ls android/app/build/outputs/apk/debug/*.apk | head -1)
+            VARIANT="debug"
+          else
+            VARIANT="release"
+          fi
+          DEST="build/LedGrab-${{ steps.label.outputs.label }}-android-${VARIANT}.apk"
+          mkdir -p build
+          cp "$SRC" "$DEST"
+          echo "path=$DEST" >> "$GITHUB_OUTPUT"
+          echo "name=$(basename "$DEST")" >> "$GITHUB_OUTPUT"
+          ls -lh "$DEST"
+
+      - name: Upload APK artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: LedGrab-${{ steps.label.outputs.label }}-android
+          path: ${{ steps.apk.outputs.path }}
+          retention-days: 90
+
+      - name: Attach APK to Gitea release (upsert)
+        if: ${{ steps.label.outputs.is_release == 'true' }}
+        env:
+          GITEA_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ gitea.ref_name }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+          APK_PATH="${{ steps.apk.outputs.path }}"
+          APK_NAME="${{ steps.apk.outputs.name }}"
+
+          if [ -z "${GITEA_TOKEN:-}" ]; then
+            echo "::error::DEPLOY_TOKEN secret not configured — cannot attach APK"
+            exit 1
+          fi
+
+          # Upsert: look up release by tag. If it exists, reuse it; if 404,
+          # create one. Makes the Android workflow self-sufficient — no
+          # ordering dependency on release.yml's create-release job.
+          HTTP=$(curl -s -o /tmp/release.json -w "%{http_code}" \
+            "$BASE_URL/releases/tags/$TAG" \
+            -H "Authorization: token $GITEA_TOKEN")
+          case "$HTTP" in
+            200)
+              RELEASE_ID=$(python3 -c "import json; print(json.load(open('/tmp/release.json'))['id'])")
+              echo "Found existing release id=$RELEASE_ID"
+              ;;
+            404)
+              echo "No release for tag $TAG — creating one"
+              IS_PRE="false"
+              if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+                IS_PRE="true"
+              fi
+              CREATE_HTTP=$(curl -s -o /tmp/created.json -w "%{http_code}" \
+                -X POST "$BASE_URL/releases" \
+                -H "Authorization: token $GITEA_TOKEN" \
+                -H "Content-Type: application/json" \
+                -d "{\"tag_name\":\"$TAG\",\"name\":\"LedGrab $TAG\",\"draft\":false,\"prerelease\":$IS_PRE}")
+              if [ "$CREATE_HTTP" != "201" ] && [ "$CREATE_HTTP" != "200" ]; then
+                echo "::error::Failed to create release (HTTP $CREATE_HTTP)"
+                cat /tmp/created.json
+                exit 1
+              fi
+              RELEASE_ID=$(python3 -c "import json; print(json.load(open('/tmp/created.json'))['id'])")
+              echo "Created release id=$RELEASE_ID"
+              ;;
+            *)
+              echo "::error::Unexpected HTTP $HTTP when looking up release for tag $TAG"
+              cat /tmp/release.json
+              exit 1
+              ;;
+          esac
+
+          # Replace existing asset if present (re-run safety).
+          EXISTING_ID=$(curl -fsS "$BASE_URL/releases/$RELEASE_ID/assets" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            | python3 -c "import sys,json; assets=json.load(sys.stdin); print(next((str(a['id']) for a in assets if a['name']=='$APK_NAME'),''))")
+          if [ -n "$EXISTING_ID" ]; then
+            curl -fsS -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$EXISTING_ID" \
+              -H "Authorization: token $GITEA_TOKEN"
+            echo "Replaced existing asset: $APK_NAME"
+          fi
+
+          # -f: exit non-zero on 4xx/5xx so a broken token fails the job
+          # loudly instead of the previous silent "Uploaded" lie.
+          curl -fsS -X POST \
+            "$BASE_URL/releases/$RELEASE_ID/assets?name=$APK_NAME" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/octet-stream" \
+            --data-binary "@$APK_PATH"
+          echo "Uploaded: $APK_NAME"

.gitea/workflows/build.yml

@@ -0,0 +1,80 @@
+name: Build Artifacts
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label (e.g. dev, 0.3.0-test)'
+        required: false
+        default: 'dev'
+
+jobs:
+  build-windows:
+    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/build-dist-windows.sh
+          ./build/build-dist-windows.sh "v${{ inputs.version }}"
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: LedGrab-${{ inputs.version }}-win-x64
+          path: |
+            build/LedGrab-*.zip
+            build/LedGrab-*-setup.exe
+          retention-days: 90
+
+  build-linux:
+    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/build-dist.sh
+          ./build/build-dist.sh "v${{ inputs.version }}"
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: LedGrab-${{ inputs.version }}-linux-x64
+          path: build/LedGrab-*.tar.gz
+          retention-days: 90

.gitea/workflows/release.yml

@@ -4,18 +4,35 @@ on:
   push:
     tags:
       - 'v*'
+  # Manual dispatch builds Windows/Linux/Docker artifacts without creating
+  # a Gitea release — for validating build scripts between real releases.
+  # Attach/push steps are gated on github.event_name == 'push'.
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label for dispatch builds (artifacts only, no release)'
+        required: false
+        default: 'dev'
 
 jobs:
   # ── Create the release first (shared by all build jobs) ────
   create-release:
+    # Skipped on workflow_dispatch — dispatch is for build validation only.
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     outputs:
       release_id: ${{ steps.create.outputs.release_id }}
     steps:
+      - name: Fetch RELEASE_NOTES.md only
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: RELEASE_NOTES.md
+          sparse-checkout-cone-mode: false
+
       - name: Create Gitea release
         id: create
         env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
         run: |
           TAG="${{ gitea.ref_name }}"
           BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
@@ -30,18 +47,36 @@ jobs:
           REPO=$(echo "${{ gitea.repository }}" | tr '[:upper:]' '[:lower:]')
           DOCKER_IMAGE="${SERVER_HOST}/${REPO}"
 
+          if [ -f RELEASE_NOTES.md ]; then
+            export RELEASE_NOTES=$(cat RELEASE_NOTES.md)
+            echo "Found RELEASE_NOTES.md"
+          else
+            export RELEASE_NOTES=""
+            echo "No RELEASE_NOTES.md found"
+          fi
+
           # Build release body via Python to avoid YAML escaping issues
           BODY_JSON=$(python3 -c "
-          import json, sys
+          import json, sys, os, textwrap
+
           tag = '$TAG'
           image = '$DOCKER_IMAGE'
-          body = f'''## Downloads
+          release_notes = os.environ.get('RELEASE_NOTES', '')
+
+          sections = []
+
+          if release_notes.strip():
+              sections.append(release_notes.strip())
+
+          sections.append(textwrap.dedent(f'''
+          ## 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 |
+          | Android | \`LedGrab-{tag}-android-release.apk\` | Sideload on Android 7.0+ (API 24+) — TV boxes, Fire TV, phones, tablets. arm64-v8a / x86_64 / x86 |
           | Docker | See below | docker pull + docker run |
 
           After starting, open **http://localhost:8080** in your browser.
@@ -55,12 +90,12 @@ jobs:
 
           ### First-time setup
 
-          1. Change the default API key in config/default_config.yaml
-          2. Open http://localhost:8080 and discover your WLED devices
-          3. See INSTALLATION.md for detailed configuration
-          '''
-          import textwrap
-          print(json.dumps(textwrap.dedent(body).strip()))
+          1. Change the default API key in `config/default_config.yaml`.
+          2. Open http://localhost:8080 and add your LED devices.
+          3. See `INSTALLATION.md` for detailed configuration.
+          ''').strip())
+
+          print(json.dumps('\n\n'.join(sections)))
           ")
 
           RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
@@ -88,6 +123,9 @@ jobs:
   # ── Windows portable ZIP (cross-built from Linux) ─────────
   build-windows:
     needs: create-release
+    # `!cancelled()` lets this job run even when create-release was skipped
+    # (dispatch) or failed. The attach step itself is still push-gated.
+    if: ${{ !cancelled() && (needs.create-release.result == 'success' || needs.create-release.result == 'skipped') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -112,8 +150,8 @@ jobs:
 
       - name: Cross-build Windows distribution
         run: |
-          chmod +x build-dist-windows.sh
-          ./build-dist-windows.sh "${{ gitea.ref_name }}"
+          chmod +x build/build-dist-windows.sh
+          ./build/build-dist-windows.sh "${{ gitea.ref_name }}"
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v3
@@ -125,8 +163,10 @@ jobs:
           retention-days: 90
 
       - name: Attach assets to release
+        # Push (tag) only — dispatch runs produce artifacts but no release.
+        if: github.event_name == 'push'
         env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
         run: |
           RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
           BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
@@ -151,15 +191,26 @@ jobs:
             echo "Uploaded: $NAME"
           }
 
+          # Publish an asset plus its .sha256 sidecar. The in-app update
+          # service refuses to install without a published checksum, so
+          # every artifact needs its hash uploaded alongside.
+          upload_with_sha256() {
+            local FILE="$1"
+            upload_asset "$FILE"
+            (cd "$(dirname "$FILE")" && sha256sum "$(basename "$FILE")" > "$(basename "$FILE").sha256")
+            upload_asset "$FILE.sha256"
+          }
+
           ZIP_FILE=$(ls build/LedGrab-*.zip | head -1)
-          [ -f "$ZIP_FILE" ] && upload_asset "$ZIP_FILE"
+          [ -f "$ZIP_FILE" ] && upload_with_sha256 "$ZIP_FILE"
 
           SETUP_FILE=$(ls build/LedGrab-*-setup.exe 2>/dev/null | head -1)
-          [ -f "$SETUP_FILE" ] && upload_asset "$SETUP_FILE"
+          [ -f "$SETUP_FILE" ] && upload_with_sha256 "$SETUP_FILE"
 
   # ── Linux tarball ──────────────────────────────────────────
   build-linux:
     needs: create-release
+    if: ${{ !cancelled() && (needs.create-release.result == 'success' || needs.create-release.result == 'skipped') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -184,8 +235,8 @@ jobs:
 
       - name: Build Linux distribution
         run: |
-          chmod +x build-dist.sh
-          ./build-dist.sh "${{ gitea.ref_name }}"
+          chmod +x build/build-dist.sh
+          ./build/build-dist.sh "${{ gitea.ref_name }}"
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v3
@@ -195,34 +246,44 @@ jobs:
           retention-days: 90
 
       - name: Attach tarball to release
+        if: github.event_name == 'push'
         env:
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
         run: |
           RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
           BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          upload_asset() {
+            local FILE="$1"
+            local NAME
+            NAME=$(basename "$FILE")
+            EXISTING_ID=$(curl -s "$BASE_URL/releases/$RELEASE_ID/assets" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              | python3 -c "import sys,json; assets=json.load(sys.stdin); print(next((str(a['id']) for a in assets if a['name']=='$NAME'),''))" 2>/dev/null)
+            if [ -n "$EXISTING_ID" ]; then
+              curl -s -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$EXISTING_ID" \
+                -H "Authorization: token $GITEA_TOKEN"
+              echo "Replaced existing asset: $NAME"
+            fi
+            curl -s -X POST \
+              "$BASE_URL/releases/$RELEASE_ID/assets?name=$NAME" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              -H "Content-Type: application/octet-stream" \
+              --data-binary "@$FILE"
+            echo "Uploaded: $NAME"
+          }
+
           TAR_FILE=$(ls build/LedGrab-*.tar.gz | head -1)
-          TAR_NAME=$(basename "$TAR_FILE")
-
-          # Delete existing asset with same name to prevent duplicates on re-run
-          EXISTING_ID=$(curl -s "$BASE_URL/releases/$RELEASE_ID/assets" \
-            -H "Authorization: token $GITEA_TOKEN" \
-            | python3 -c "import sys,json; assets=json.load(sys.stdin); print(next((str(a['id']) for a in assets if a['name']=='$TAR_NAME'),''))" 2>/dev/null)
-          if [ -n "$EXISTING_ID" ]; then
-            curl -s -X DELETE "$BASE_URL/releases/$RELEASE_ID/assets/$EXISTING_ID" \
-              -H "Authorization: token $GITEA_TOKEN"
-            echo "Replaced existing asset: $TAR_NAME"
+          if [ -f "$TAR_FILE" ]; then
+            upload_asset "$TAR_FILE"
+            (cd "$(dirname "$TAR_FILE")" && sha256sum "$(basename "$TAR_FILE")" > "$(basename "$TAR_FILE").sha256")
+            upload_asset "$TAR_FILE.sha256"
           fi
 
-          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
+    if: ${{ !cancelled() && (needs.create-release.result == 'success' || needs.create-release.result == 'skipped') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -246,14 +307,20 @@ jobs:
 
       - name: Login to Gitea Container Registry
         id: docker-login
+        # Dispatch runs don't need registry credentials — the build step
+        # verifies the Dockerfile locally and push is skipped.
+        if: github.event_name == 'push'
         continue-on-error: true
         run: |
-          echo "${{ secrets.GITEA_TOKEN }}" | docker login \
+          echo "${{ secrets.DEPLOY_TOKEN }}" | docker login \
             "${{ steps.meta.outputs.server_host }}" \
             -u "${{ gitea.actor }}" --password-stdin
 
       - name: Build Docker image
-        if: steps.docker-login.outcome == 'success'
+        # Always build — dispatch uses this to validate the Dockerfile.
+        # On push, still gate on successful login so we don't build a
+        # tagged image that can't be pushed.
+        if: github.event_name != 'push' || steps.docker-login.outcome == 'success'
         run: |
           TAG="${{ gitea.ref_name }}"
           REGISTRY="${{ steps.meta.outputs.registry }}"
@@ -272,7 +339,7 @@ jobs:
           fi
 
       - name: Push Docker image
-        if: steps.docker-login.outcome == 'success'
+        if: github.event_name == 'push' && steps.docker-login.outcome == 'success'
         run: |
           TAG="${{ gitea.ref_name }}"
           REGISTRY="${{ steps.meta.outputs.registry }}"

.gitea/workflows/test.yml

@@ -5,9 +5,15 @@ on:
     branches: [master]
   pull_request:
     branches: [master]
+  # Allow manual runs (e.g. to validate after a release commit was skipped).
+  workflow_dispatch:
 
 jobs:
   test:
+    # Skip release-publishing commits — version bumps don't affect lint/tests
+    # and the release.yml pipeline is already running. PRs and manual dispatch
+    # always run.
+    if: ${{ github.event_name != 'push' || !startsWith(github.event.head_commit.message, 'chore: release') }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.gitignore

@@ -4,7 +4,16 @@ __pycache__/
 *$py.class
 *.so
 .Python
-build/
+# Build output artifacts (LedGrab/, *.zip, *.exe, *.tar.gz, cached downloads)
+build/LedGrab/
+build/*.zip
+build/*.exe
+build/*.tar.gz
+build/*.msi
+build/python-embed-*.zip
+build/pip-wheels/
+build/win-wheels/
+build/tk-extract/
 develop-eggs/
 dist/
 downloads/
@@ -16,6 +25,10 @@ parts/
 sdist/
 var/
 wheels/
+# …but keep pre-built Android wheels (pydantic-core cross-compiled for
+# arm64-v8a / x86_64 / x86, required by the Chaquopy build)
+!android/wheels/
+!android/wheels/*
 *.egg-info/
 .installed.cfg
 *.egg
@@ -49,8 +62,17 @@ htmlcov/
 logs/
 *.log.*
 
-# Runtime data
-data/
+# Runtime data — anchor to repo root so nested package data dirs
+# (server/src/ledgrab/data/prebuilt_sounds, game_adapters) are NOT ignored.
+# An unanchored `data/` rule silently broke the v0.4.2 release by keeping
+# shipped sound assets out of the CI tag checkout.
+/data/
+/server/data/
+# Defensive: if the server is launched from server/src/ (uncommon path),
+# its relative `data/` dir resolves to server/src/data/. Templates now
+# live in SQLite, so any *.json that lands here is stale runtime export
+# and must not be committed.
+/server/src/data/
 *.db
 *.sqlite
 *.json.bak
@@ -73,3 +95,8 @@ tmp/
 # OS
 Thumbs.db
 .DS_Store
+# Added by code-review-graph
+.code-review-graph/
+
+# vex semantic-search embedding cache (auto-downloaded on first --semantic run)
+.fastembed_cache/

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "code-review-graph": {
+      "command": "uvx",
+      "args": [
+        "code-review-graph",
+        "serve"
+      ],
+      "type": "stdio"
+    }
+  }
+}

.pre-commit-config.yaml

@@ -4,10 +4,12 @@ repos:
     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
+    # Bumped from v0.8.0 so the hook recognises UP045
+    # (non-pep604-annotation-optional), which the v0.13+ ruff split off
+    # from UP007. Pyproject.toml extend-selects both rules.
+    rev: v0.15.12
     hooks:
       - id: ruff
         args: [--line-length=100, --target-version=py311]

.vex.toml

@@ -0,0 +1,24 @@
+# vex configuration — https://github.com/tenatarika/vex
+#
+# Place this file in your project root as .vex.toml
+
+# Glob patterns to exclude from indexing (gitignore syntax, on top of .gitignore)
+# exclude = [
+#     "vendor/**",
+#     "node_modules/**",
+#     "*.generated.go",
+#     "dist/**",
+# ]
+
+# Default output format: "text", "json", or "compact"
+# format = "text"
+
+# Enable semantic embeddings by default (slower indexing, enables meaning-based search)
+semantic = true
+
+# Automatically run `vex update` before search if the index is stale
+auto_update = true
+
+# Embedder used for semantic indexing. Known IDs: minilm-l6-v2 (default).
+# Changing the embedder requires a full reindex.
+# embedder = "minilm-l6-v2"

AUDIT_REMAINING.md

@@ -0,0 +1,347 @@
+# LedGrab Architecture Audit — Remaining Items
+
+Roadmap for the architecture-audit refactor sprint that started 2026-05-22.
+This file lists every audit finding that is **not yet addressed**; the ones
+already landed in commits `563cbac..2f15fbb` are summarised below for
+context.
+
+## Already done (10 commits)
+
+| Commit | Findings addressed |
+|---|---|
+| `563cbac` | C2, C11, C1 (parallel-change only), C3, C4, C6, C7-streams |
+| `29bdacf` | C5 (HA/Z2M swap helper; full ABC deferred) |
+| `97dae2c` | H1 |
+| `5fec8db` | M4 |
+| `98fb61d` | H2 |
+| `9f3f346` | M5 |
+| `05f73ee` | H6 (bindable extraction only) |
+| `3b8f00e` + `c1aa2eb` | C7 store-side |
+| `2f15fbb` | H3 |
+
+All commits have ≥1 code-review subagent pass with HIGH findings fixed
+before commit. Tests pass on each commit; ruff clean; tsc + bundle build
+clean for the frontend commit.
+
+The two CRITICAL **data-safety** items (C2 silent CSS fallback, C11
+string-replace JSON migration) are fixed. The two CRITICAL
+**parallel-change** problems for color-strip + value-source dispatch are
+fixed. The two HIGH dispatch problems (H1 effects, H2 rules) are fixed.
+
+---
+
+## Remaining backend items
+
+### HIGH
+
+#### H4 — `Device.__init__` 40+ params mixing per-type fields
+
+**File:** `server/src/ledgrab/storage/device_store.py:46-150`
+
+The `Device` dataclass constructor accepts ~40 parameters that mix common
+fields with DMX-only / DDP-only / Hue-only / Yeelight-only / Wiz-only /
+LIFX-only / Govee-only / Nanoleaf-only / SPI-only / Chroma-only /
+GameSense-only fields. Setting `hue_username` on a WLED device is
+silently ignored.
+
+**Approach:** introduce per-device-type config dataclasses
+(`DmxConfig`, `HueConfig`, `DdpConfig`, …) and make `Device.config` a
+discriminated union. Per-type validation moves to the config classes.
+Wire migration: every existing device row needs to be re-parsed; use the
+versioned `MigrationRunner` introduced in Phase 1.2.
+
+**Risk:** medium-high. Touches:
+- `storage/device_store.py` — Device dataclass, `from_dict`, `to_dict`,
+  `create_device`, `update_device`
+- `api/schemas/devices.py` — Pydantic schemas
+- `api/routes/devices.py` — request validation
+- `core/devices/*` — every provider reads device fields
+- A new migration to translate flat fields → nested `config`
+
+**Estimated scope:** ~1500 LOC diff, 1-2 dedicated sessions.
+
+#### H5 — `WledTargetProcessor` god class (32 methods, 5 responsibilities)
+
+**File:** `server/src/ledgrab/core/processing/wled_target_processor.py` (1238 LOC)
+
+Conflates:
+1. Device connectivity (probe, liveness, reconnect)
+2. FPS negotiation (adaptive_fps, keepalive_interval, state_check_interval)
+3. LED resampling (`_fit_to_device` — 60 lines of numpy)
+4. Preview WebSocket fanout (`_preview_clients`, `_broadcast_led_preview`)
+5. Metrics emission (`get_state`, `get_metrics`)
+
+**Approach:** extract `WledDeviceConnector`, `WledPixelSender`,
+`TargetFitProcessor`, `TargetPreviewBroadcaster`, `TargetMetricsCollector`.
+`WledTargetProcessor` becomes an orchestrator that composes them.
+
+**Risk:** HIGHEST in the audit. This class drives physical LED hardware
+in production. A regression caught at runtime (in the user's living
+room) is the expensive failure mode. Needs manual verification with at
+least one real WLED device after the refactor.
+
+**Coupled with:** C5 (HA/Z2M shared the same shape; should extract a
+common `BaseTargetProcessor` ABC at the same time so all three
+processors share lifecycle / preview / metrics code).
+
+**Estimated scope:** ~2000 LOC diff, 2-3 dedicated sessions, with manual
+device testing after each.
+
+#### H7 — `device-discovery.ts` 1745 LOC
+
+Frontend mirror of H4. The `onDeviceTypeChanged` handler has a giant
+switch with 15+ device kinds and 15+ `_showXxxFields` / `_buildXxxItems`
+helpers. Adding a device type requires editing 5 separate frontend hooks.
+
+**Approach:** mirror the H4 backend redesign — once the storage layer
+has per-type config objects, the frontend can have a per-type field-set
+registry. Best done **after** H4 lands so the schemas drive the
+registry.
+
+**Estimated scope:** 1-2 sessions; coupled to H4.
+
+#### H8 — `automations.ts` 1410 LOC
+
+Frontend mirror of H2 (rule polymorphism). Already addressed on the
+backend in `98fb61d`; the frontend dispatch on `RuleType` is still
+hand-rolled.
+
+**Approach:** introduce a rule-type registry on the frontend matching
+the backend's `_RULE_HANDLERS` shape.
+
+**Estimated scope:** half a session.
+
+### MEDIUM
+
+#### M1 — `ProcessorManager.add_target` shotgun (11 args, WLED-leak)
+
+**File:** `server/src/ledgrab/core/processing/processor_manager.py:396`
+
+Method is named generically (`add_target`) but accepts `protocol="ddp"`
+and `keepalive_interval` — WLED-only fields. HA and Z2M have sibling
+methods with their own bespoke params.
+
+**Approach:** extract a `TargetFactory` (per-kind builders, similar to
+`value_source_factories.py` from Phase 7). Couple with H5/C5 work.
+
+#### M2 — `TargetContext` god-bag
+
+**File:** `server/src/ledgrab/core/processing/processor_manager.py`
+
+`@dataclass TargetContext` exposes ~8 attributes (device_store,
+color_strip_stream_manager, value_stream_manager, metrics_history,
+mqtt_manager, ha_manager, …). Processors silently depend on whichever
+fields they read. Tests have to construct a huge mock context.
+
+**Approach:** make per-processor explicit dependency injection. Couple
+with H5 work.
+
+#### M3 — Validation duplicated across layers
+
+Field-level constraints (composite nesting depth, name uniqueness, span
+ranges) are enforced in route + schema + store. Adding a new constraint
+means editing 3 places.
+
+**Approach:** move all validation to the model/schema layer (Pydantic
+validators + dataclass `__post_init__`). Routes trust the schema; store
+trusts the model.
+
+**Risk:** moderate — cross-cutting; needs careful review of which layer
+currently owns which constraint.
+
+#### M6 — `ws_stream.py` mixed concerns (699 LOC)
+
+**File:** `server/src/ledgrab/api/routes/color_strip_sources/ws_stream.py`
+
+The worst part (stream-creation dispatch) was fixed in Phase 2.1 — it
+now calls `color_strip_kinds.build_stream(source, deps)`. The remaining
+699 lines mix config parsing + WebSocket lifecycle + frame loop. Could
+extract the frame loop into a separate `PreviewFrameLoop` class.
+
+**Estimated scope:** half a session. Low impact since the parallel-change
+problem is already fixed.
+
+#### M7 — No shared frontend API client
+
+**File:** every `static/js/features/*.ts`
+
+`fetchWithAuth(...)` + bespoke error-unwrapping is copy-pasted in every
+feature's save / load function. ~25 files.
+
+**Approach:** introduce `static/js/core/api-client.ts` with typed
+methods (`get`, `post`, `put`, `delete`) that handle auth, JSON parsing,
+error normalisation. Replace `fetchWithAuth` calls across features.
+
+#### M8 — Global `_cached*` `let` vars
+
+Mutable module-level state mutated from multiple feature modules. No
+subscription model — features manually `invalidate()` after CRUD.
+
+**Approach:** introduce a reactive cache (EventEmitter pattern or a tiny
+store like Nano Stores). Couple with M7 (the API client can drive cache
+invalidation on write).
+
+#### M9 — `dashboard.ts` 1421 LOC
+
+Frontend god-module orchestrating + rendering device / target / CSS
+cards. Couple with C8/C9/C10 frontend split work.
+
+#### M10 — Duplicate frontend modal classes
+
+`ValueSourceModal`, `StreamEditorModal`, `TargetEditorModal`,
+`AddDeviceModal`, etc. each reimplement pristine-check / undo / focus
+management.
+
+**Approach:** introduce a `FormModal<T>` base class.
+
+#### M11 — Hardcoded `_getSectionForSource` / `_getTabForSource`
+
+Routing tables duplicated across multiple feature files (streams.ts,
+value-sources.ts). Adding a new stream type requires hunting strings.
+
+**Approach:** single routing registry keyed by source_type.
+
+#### M12 — Late imports masking cycles
+
+Partially addressed by the kind registries (Phase 2.1, 2.2). Some
+late-imports still exist in `value_stream.py`, `audio_stream.py`, the
+target processors. Resolving them requires restructuring module layout
+to break the circular dependencies.
+
+**Estimated scope:** small follow-up after H5.
+
+### LOW
+
+#### L1 — `(src as any).field` casts in `value-sources.ts`
+
+Discriminated unions aren't narrowed properly. Couple with C8 frontend
+split.
+
+#### L2 — Mutable state without locks
+
+`_preview_clients`, `_last_preview_data`, `_color_stream`,
+`_css_stream` are mutated from multiple async tasks without explicit
+locks. Production has not exhibited issues but the contract is fragile.
+
+**Approach:** add explicit `asyncio.Lock` per processor. Couple with H5.
+
+#### L3 — `Calibration.validate()` raises instead of returning result
+
+**File:** `server/src/ledgrab/core/capture/calibration.py:164`
+
+All 4 call sites currently rely on the raise; converting to
+`ValidationResult` would force every caller to check a return value
+without adding safety. **Recommendation:** skip — current design is
+appropriate.
+
+#### L4 — `_SOURCE_TYPE_MAP` is module-private
+
+No public `GET /api/v1/source-types` discovery endpoint. Frontend
+hardcodes the list of source types in `types.ts`.
+
+**Approach:** add a discovery route + matching frontend fetch. Couple
+with H6 frontend split (since `types.ts` is involved).
+
+#### L5 — `AudioValueStream` implicit state machine
+
+**File:** `server/src/ledgrab/core/processing/value_stream.py:169-383`
+
+`get_value()` can be called before `start()`; transitions are implicit.
+**Approach:** explicit State pattern. Low value (production callers
+always start before reading).
+
+---
+
+## Remaining frontend items (all)
+
+### CRITICAL
+
+- **C8** — `value-sources.ts` 1972 LOC (4 god-functions, type-dispatch ladders)
+- **C9** — `graph-editor.ts` 2707 LOC (layout + interaction + state + WS sync + …)
+- **C10** — `streams.ts` 2341 LOC (picture / audio / template kitchen-sink)
+
+### Other frontend (severity in main list above)
+
+- **H6 rest** — split remaining ~1100 LOC of `types.ts` into per-entity files
+- **H7** — `device-discovery.ts` 1745 LOC (couple with H4)
+- **H8** — `automations.ts` 1410 LOC (mirror H2)
+- **M7** — shared API client
+- **M8** — reactive cache
+- **M9** — `dashboard.ts` 1421 LOC
+- **M10** — `FormModal<T>` base
+- **M11** — routing registry
+- **L1** — narrowing the discriminated unions
+
+The frontend remainder is **multi-day work** even when broken up by
+finding. Recommended approach: a dedicated frontend sprint with the
+typescript-reviewer agent + manual UI testing for each god-module
+split. Order:
+
+1. Finish `types.ts` split (H6) — pure organisation, low risk, unblocks
+   the rest
+2. Introduce API client (M7) — every feature file gains a cleaner shape
+3. Split `value-sources.ts` (C8) — uses the API client + per-type
+   registry pattern
+4. Split `streams.ts` (C10)
+5. Split `graph-editor.ts` (C9) — needs the most care; the file owns
+   the entire visual editor
+6. Polish: `dashboard.ts` (M9), `device-discovery.ts` (H7),
+   `automations.ts` (H8), `FormModal` (M10), routing registry (M11),
+   reactive cache (M8), narrowing (L1)
+
+---
+
+## Recommended ordering for future sessions
+
+### Session A — Frontend sprint (multi-day)
+
+Address H6-rest, C8, C9, C10, H7, H8, M7-M11, L1. See order above.
+Critical to have typescript-reviewer feedback + manual UI testing after
+each split.
+
+### Session B — Device redesign (1-2 sessions)
+
+Address H4 alone. Touches device storage + provider classes; needs a
+data migration. Once H4 lands, H7 frontend mirror can follow.
+
+### Session C — BaseTargetProcessor ABC (2-3 sessions)
+
+Address C5 (full) + H5 + M1 + M2 + L2 together. Highest risk in the
+audit because it drives physical LED hardware. Each step needs manual
+verification with a real device.
+
+### Session D — Polish (half a session)
+
+Address M3, M6 (remainder), M12 (remainder), L3 (decision: skip), L4,
+L5.
+
+---
+
+## Pattern reference for new contributors
+
+Three registry-pattern templates that already exist in the codebase and
+should be the model for the remaining dispatch ladders:
+
+1. **Class-level handler dict + import-time coverage assertion**
+   - `core/processing/effect_stream.py::_RENDERERS`
+     (`@_effect_renderer` decorator + `@_collect_effect_renderers`
+     class decorator)
+   - `core/automations/automation_engine.py::AutomationEngine._RULE_HANDLERS`
+     (module-level binding after class definition)
+   - `api/routes/output_targets.py::_TARGET_RESPONSE_BUILDERS`
+     (response-shape dispatch keyed by storage class)
+
+2. **Per-type free functions + dependency-bag dataclass**
+   - `core/processing/color_strip_kinds.py` (`StreamDeps` + `STREAM_BUILDERS`)
+   - `core/processing/value_kinds.py` (`ValueStreamDeps` + `STREAM_BUILDERS`)
+   - `storage/value_source_factories.py` (`CREATE_BUILDERS` + `UPDATE_APPLIERS`)
+
+3. **Versioned migration runner**
+   - `storage/data_migrations.py` (`MigrationRunner` + `DataMigration` ABC)
+   - Used for any storage rename / field-shape change in the future.
+   - Audit-table contract: atomic transaction covers
+     applied-check + apply + record, so partial-failure cannot leave
+     data rewritten but unrecorded.
+
+Adding a new feature that touches dispatch should reach for one of
+these three patterns before writing a fresh if/elif chain.

BRAINSTORM.md

@@ -1,118 +0,0 @@
-# Feature Brainstorm — LED Grab
-
-## New Automation Conditions (Profiles)
-
-Right now profiles only trigger on **app detection**. High-value additions:
-
-- **Time-of-day / Schedule** — "warm tones after sunset, off at midnight." Schedule-based value sources pattern already exists
-- **Display state** — detect monitor on/off/sleep, auto-stop targets when display is off
-- **System idle** — dim or switch to ambient effect after N minutes of no input
-- **Sunrise/sunset** — fetch local solar times, drive circadian color temperature shifts
-- **Webhook/MQTT trigger** — let external systems activate profiles without HA integration
-
-## New Output Targets
-
-Currently: WLED, Adalight, AmbileD, DDP. Potential:
-
-- **MQTT publish** — generic IoT output, any MQTT subscriber becomes a target
-- **Art-Net / sACN (E1.31)** — stage/theatrical lighting protocols, DMX controllers
-- **OpenRGB** — control PC peripherals (keyboard, mouse, RAM, fans) as ambient targets
-- **HTTP webhook** — POST color data to arbitrary endpoints
-- **Recording target** — save color streams to file for playback later
-
-## New Color Strip Sources
-
-- **Spotify / media player** — album art color extraction or tempo-synced effects
-- **Weather** — pull conditions from API, map to palettes (blue=rain, orange=sun, white=snow)
-- **Camera / webcam** — border-sampling from camera feed for video calls or room-reactive lighting
-- **Script source** — user-written JS/Python snippets producing color arrays per frame
-- **Notification reactive** — flash/pulse on OS notifications (optional app filter)
-
-## Processing Pipeline Extensions
-
-- **Palette quantization** — force output to match a user-defined palette
-- **Zone grouping** — merge adjacent LEDs into logical groups sharing one averaged color
-- **Color temperature filter** — warm/cool shift separate from hue shift (circadian/mood)
-- **Noise gate** — suppress small color changes below threshold, preventing shimmer on static content
-
-## Multi-Instance & Sync
-
-- **Multi-room sync** — multiple instances with shared clock for synchronized effects
-- **Multi-display unification** — treat 2-3 monitors as single virtual display for seamless ambilight
-- **Leader/follower mode** — one target's output drives others with optional delay (cascade)
-
-## UX & Dashboard
-
-- **PWA / mobile layout** — mobile-first layout + "Add to Home Screen" manifest
-- **Scene presets** — bundled source + filters + brightness as one-click presets ("Movie night", "Gaming")
-- **Live preview on dashboard** — miniature screen with LED colors rendered around its border
-- **Undo/redo for calibration** — reduce frustration in the fiddly calibration editor
-- **Drag-and-drop filter ordering** — reorder postprocessing filter chains visually
-
-## API & Integration
-
-- **WebSocket event bus** — broadcast all state changes over a single WS channel
-- **OBS integration** — detect active scene, switch profiles; or use OBS virtual camera as source
-- **Plugin system** — formalize extension points into documented plugin API with hot-reload
-
-## Creative / Fun
-
-- **Effect sequencer** — timeline-based choreography of effects, colors, and transitions
-- **Music BPM sync** — lock effect speed to detected BPM (beat detection already exists)
-- **Color extraction from image** — upload photo, extract palette, use as gradient/cycle source
-- **Transition effects** — crossfade, wipe, or dissolve between sources/profiles instead of instant cut
-
----
-
-## Deep Dive: Notification Reactive Source
-
-**Type:** New `ColorStripSource` (`source_type: "notification"`) — normally outputs transparent RGBA, flashes on notification events. Designed to be used as a layer in a **composite source** so it overlays on top of a persistent base (gradient, effect, screen capture, etc.).
-
-### Trigger modes (both active simultaneously)
-
-1. **OS listener (Windows)** — `pywinrt` + `Windows.UI.Notifications.Management.UserNotificationListener`. Runs in background thread, pushes events to source via queue. Windows-only for now; macOS (`pyobjc` + `NSUserNotificationCenter`) and Linux (`dbus` + `org.freedesktop.Notifications`) deferred to future.
-2. **Webhook** — `POST /api/v1/notifications/{source_id}/fire` with optional body `{ "app": "MyApp", "color": "#FF0000" }`. Always available, cross-platform by nature.
-
-### Source config
-
-```yaml
-os_listener: true           # enable Windows notification listener
-app_filter:
-  mode: whitelist|blacklist  # which apps to react to
-  apps: [Discord, Slack, Telegram]
-app_colors:                  # user-configured app → color mapping
-  Discord: "#5865F2"
-  Slack: "#4A154B"
-  Telegram: "#26A5E4"
-default_color: "#FFFFFF"     # fallback when app has no mapping
-effect: flash|pulse|sweep    # visual effect type
-duration_ms: 1500            # effect duration
-```
-
-### Effect rendering
-
-Source outputs RGBA color array per frame:
-- **Idle**: all pixels `(0,0,0,0)` — composite passes through base layer
-- **Flash**: instant full-color, linear fade to transparent over `duration_ms`
-- **Pulse**: sine fade in/out over `duration_ms`
-- **Sweep**: color travels across the strip like a wave
-
-Each notification starts its own mini-timeline from trigger timestamp (not sync clock).
-
-### Overlap handling
-
-New notification while previous effect is active → restart timer with new color. No queuing.
-
-### App color resolution
-
-1. Webhook body `color` field (explicit override) → highest priority
-2. `app_colors` mapping by app name
-3. `default_color` fallback
-
----
-
-## Top Picks (impact vs effort)
-
-1. **Time-of-day + idle profile conditions** — builds on existing profile/condition architecture
-2. **MQTT output target** — opens the door to an enormous IoT ecosystem
-3. **Scene presets** — purely frontend, bundles existing features into one-click UX

CLAUDE.md

@@ -1,4 +1,4 @@
-# Claude Instructions for WLED Screen Controller
+# Claude Instructions for LedGrab
 
 ## Code Search
 
@@ -28,8 +28,21 @@ ast-index changed --base master           # Show symbols changed in current bran
 ## Project Structure
 
 - `/server` — Python FastAPI backend (see [server/CLAUDE.md](server/CLAUDE.md))
+- `/android` — Android TV app (Kotlin shell + embedded Python via Chaquopy)
 - `/contexts` — Context files for Claude (frontend conventions, graph editor, Chrome tools, server ops, demo mode)
 
+## Android Dependency Sync (CRITICAL)
+
+The Android app (`android/app/build.gradle.kts`) installs the server package with `--no-deps` and lists Android-compatible dependencies **explicitly** in the Chaquopy `pip {}` block. This is because `server/pyproject.toml` includes desktop-only packages (mss, psutil, sounddevice, etc.) that have no Android wheels.
+
+**When adding a new dependency to `server/pyproject.toml`:**
+
+1. If the package is **pure Python or has Chaquopy wheels** (check [Chaquopy PyPI](https://chaquo.com/pypi-13.1/)), also add it to `android/app/build.gradle.kts` in the `pip { install(...) }` block
+2. If the package is **desktop-only** (native C/Rust extension without Android support), do NOT add it to `build.gradle.kts` — and guard its import with `try/except ImportError` in Python code
+3. If unsure, check Chaquopy's package index first
+
+**Incident context:** Chaquopy's pip runs on the build machine (Windows), not on Android. Platform markers like `sys_platform != 'linux'` evaluate against the BUILD host, not the target device. `pip install --exclude` does not exist. The only reliable way to exclude packages is to not list them.
+
 ## Context Files
 
 | File | When to read |
@@ -42,10 +55,6 @@ ast-index changed --base master           # Show symbols changed in current bran
 | [Gitea Python CI/CD Guide](https://git.dolgolyov-family.by/alexei.dolgolyov/claude-code-facts/src/branch/main/gitea-python-ci-cd.md) | Reusable CI/CD patterns: Gitea Actions, cross-build, NSIS, Docker |
 | [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`.
-
 ## Documentation Lookup
 
 **Use context7 MCP tools for library/framework documentation lookups** (FastAPI, OpenCV, Pydantic, yt-dlp, etc.) instead of relying on potentially outdated training data.
@@ -91,3 +100,42 @@ Do NOT commit code that fails linting or tests. Fix the issues first.
 - Follow existing code style and patterns
 - Update documentation when changing behavior
 - Never make commits or pushes without explicit user approval
+
+<!-- code-review-graph MCP tools -->
+## MCP Tools: code-review-graph
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
+the codebase.** The graph is faster, cheaper (fewer tokens), and gives
+you structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### When to use graph tools FIRST
+
+- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
+- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
+- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
+- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
+- **Architecture questions**: `get_architecture_overview` + `list_communities`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
+
+### Key Tools
+
+| Tool | Use when |
+|------|----------|
+| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
+| `get_review_context` | Need source snippets for review — token-efficient |
+| `get_impact_radius` | Understanding blast radius of a change |
+| `get_affected_flows` | Finding which execution paths are impacted |
+| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
+| `semantic_search_nodes` | Finding functions/classes by name or keyword |
+| `get_architecture_overview` | Understanding high-level codebase structure |
+| `refactor_tool` | Planning renames, finding dead code |
+
+### Workflow
+
+1. The graph auto-updates on file changes (via hooks).
+2. Use `detect_changes` for code review.
+3. Use `get_affected_flows` to understand impact.
+4. Use `query_graph` pattern="tests_for" to check coverage.

CONTRIBUTING.md

@@ -9,8 +9,8 @@
 ## Development Setup
 
 ```bash
-git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
-cd wled-screen-controller-mixed/server
+git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
+cd ledgrab/server
 
 # Python environment
 python -m venv venv
@@ -29,7 +29,7 @@ npm run build
 cd server
 export PYTHONPATH=$(pwd)/src   # Linux/Mac
 # set PYTHONPATH=%CD%\src      # Windows
-python -m wled_controller.main
+python -m ledgrab.main
 ```
 
 Open http://localhost:8080 to access the dashboard.
@@ -55,7 +55,7 @@ ruff check src/ tests/
 
 ## Frontend Changes
 
-After modifying any file under `server/src/wled_controller/static/js/` or `static/css/`, rebuild the bundle:
+After modifying any file under `server/src/ledgrab/static/js/` or `static/css/`, rebuild the bundle:
 
 ```bash
 cd server

INSTALLATION.md

@@ -1,15 +1,17 @@
 # Installation Guide
 
-Complete installation guide for LED Grab (WLED Screen Controller) server and Home Assistant integration.
+Complete installation guide for the LedGrab server.
 
 ## Table of Contents
 
 1. [Docker Installation (recommended)](#docker-installation)
 2. [Manual Installation](#manual-installation)
 3. [First-Time Setup](#first-time-setup)
-4. [Home Assistant Integration](#home-assistant-integration)
-5. [Configuration Reference](#configuration-reference)
-6. [Troubleshooting](#troubleshooting)
+4. [Configuration Reference](#configuration-reference)
+5. [Troubleshooting](#troubleshooting)
+
+> **Home Assistant integration** has moved to a separate repository:
+> [ledgrab-haos-integration](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration)
 
 ---
 
@@ -20,8 +22,8 @@ The fastest way to get running. Requires [Docker](https://docs.docker.com/get-do
 1. **Clone and start:**
 
    ```bash
-   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
-   cd wled-screen-controller/server
+   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
+   cd ledgrab/server
    docker compose up -d
    ```
 
@@ -54,7 +56,7 @@ cd server
 docker build -t ledgrab .
 
 docker run -d \
-  --name wled-screen-controller \
+  --name ledgrab \
   -p 8080:8080 \
   -v $(pwd)/data:/app/data \
   -v $(pwd)/logs:/app/logs \
@@ -84,8 +86,8 @@ Screen capture from inside a container requires X11 access. Uncomment `network_m
 1. **Clone the repository:**
 
    ```bash
-   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
-   cd wled-screen-controller/server
+   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
+   cd ledgrab/server
    ```
 
 2. **Build the frontend bundle:**
@@ -95,7 +97,7 @@ Screen capture from inside a container requires X11 access. Uncomment `network_m
    npm run build
    ```
 
-   This compiles TypeScript and bundles JS/CSS into `src/wled_controller/static/dist/`.
+   This compiles TypeScript and bundles JS/CSS into `src/ledgrab/static/dist/`.
 
 3. **Create a virtual environment:**
 
@@ -121,7 +123,6 @@ Screen capture from inside a container requires X11 access. Uncomment `network_m
    Optional extras:
 
    ```bash
-   pip install ".[camera]"          # Webcam capture via OpenCV
    pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
    pip install ".[notifications]"   # OS notification capture
    pip install ".[dev]"             # pytest, black, ruff (development)
@@ -132,11 +133,11 @@ Screen capture from inside a container requires X11 access. Uncomment `network_m
    ```bash
    # Linux / macOS
    export PYTHONPATH=$(pwd)/src
-   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
+   uvicorn ledgrab.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
+   uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
    ```
 
 6. **Verify:** open <http://localhost:8080> in your browser.
@@ -155,13 +156,13 @@ Option A -- edit the config file:
 # server/config/default_config.yaml
 auth:
   api_keys:
-    main: "your-secure-key-here"   # replace the dev key
+    dev: "your-secure-key-here"   # replace the dev key
 ```
 
 Option B -- set an environment variable:
 
 ```bash
-export WLED_AUTH__API_KEYS__main="your-secure-key-here"
+export LEDGRAB_AUTH__API_KEYS__dev="your-secure-key-here"
 ```
 
 Generate a random key:
@@ -185,7 +186,7 @@ server:
 Or via environment variable:
 
 ```bash
-WLED_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
+LEDGRAB_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
 ```
 
 ### Discover devices
@@ -194,57 +195,12 @@ Open the dashboard and go to the **Devices** tab. Click **Discover** to find WLE
 
 ---
 
-## Home Assistant Integration
-
-### Option 1: HACS (recommended)
-
-1. Install [HACS](https://hacs.xyz/docs/setup/download) if you have not already.
-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.
-
-### Option 2: Manual
-
-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.
-
-### Automation example
-
-```yaml
-automation:
-  - alias: "Start ambient lighting when TV turns on"
-    trigger:
-      - platform: state
-        entity_id: media_player.living_room_tv
-        to: "on"
-    action:
-      - service: switch.turn_on
-        target:
-          entity_id: switch.living_room_tv_processing
-
-  - alias: "Stop ambient lighting when TV turns off"
-    trigger:
-      - platform: state
-        entity_id: media_player.living_room_tv
-        to: "off"
-    action:
-      - service: switch.turn_off
-        target:
-          entity_id: switch.living_room_tv_processing
-```
-
----
-
 ## 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)
+1. **Environment variables** -- prefix `LEDGRAB_`, double underscore as nesting delimiter (e.g., `LEDGRAB_SERVER__PORT=9090`)
+2. **YAML config file** -- `server/config/default_config.yaml` (or set `LEDGRAB_CONFIG_PATH` to override)
 3. **Built-in defaults**
 
 See [`server/.env.example`](server/.env.example) for every available variable with descriptions.
@@ -253,13 +209,14 @@ See [`server/.env.example`](server/.env.example) for every available variable wi
 
 | 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) |
+| `LEDGRAB_SERVER__PORT` | `8080` | HTTP listen port |
+| `LEDGRAB_SERVER__LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `LEDGRAB_SERVER__CORS_ORIGINS` | `["http://localhost:8080"]` | Allowed CORS origins (JSON array) |
+| `LEDGRAB_AUTH__API_KEYS` | `{"dev":"development-key..."}` | API keys (JSON object) |
+| `LEDGRAB_STORAGE__DATABASE_FILE` | `data/ledgrab.db` | SQLite database path |
+| `LEDGRAB_MQTT__ENABLED` | `false` | Enable MQTT for HA auto-discovery |
+| `LEDGRAB_MQTT__BROKER_HOST` | `localhost` | MQTT broker address |
+| `LEDGRAB_DEMO` | `false` | Enable demo mode (sandbox with virtual devices) |
 
 ---
 
@@ -276,7 +233,7 @@ python --version  # must be 3.11+
 **Check the frontend bundle exists:**
 
 ```bash
-ls server/src/wled_controller/static/dist/app.bundle.js
+ls server/src/ledgrab/static/dist/app.bundle.js
 ```
 
 If missing, run `cd server && npm ci && npm run build`.
@@ -288,7 +245,7 @@ If missing, run `cd server && npm ci && npm run build`.
 docker compose logs -f
 
 # Manual install
-tail -f logs/wled_controller.log
+tail -f logs/ledgrab.log
 ```
 
 ### Cannot access the dashboard from another machine
@@ -297,13 +254,6 @@ tail -f logs/wled_controller.log
 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.
@@ -324,4 +274,4 @@ tail -f logs/wled_controller.log
 
 - [API Documentation](docs/API.md)
 - [Calibration Guide](docs/CALIBRATION.md)
-- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues)
+- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/issues)

README.md

@@ -87,8 +87,8 @@ A Home Assistant integration exposes devices as entities for smart home automati
 ### Docker (recommended)
 
 ```bash
-git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
-cd wled-screen-controller/server
+git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
+cd ledgrab/server
 docker compose up -d
 ```
 
@@ -97,8 +97,8 @@ docker compose up -d
 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
+git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
+cd ledgrab/server
 
 # Build the frontend bundle
 npm ci && npm run build
@@ -112,7 +112,7 @@ 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
+uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
 ```
 
 Open **http://localhost:8080** to access the dashboard.
@@ -121,12 +121,32 @@ Open **http://localhost:8080** to access the dashboard.
 
 See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and Home Assistant setup.
 
+## Demo Mode
+
+Demo mode runs the server with virtual devices, sample data, and isolated storage — useful for exploring the UI without real hardware.
+
+Set the `LEDGRAB_DEMO` environment variable to `true`, `1`, or `yes`:
+
+```bash
+# Docker
+docker compose run -e LEDGRAB_DEMO=true server
+
+# Python
+LEDGRAB_DEMO=true uvicorn ledgrab.main:app --host 0.0.0.0 --port 8081
+
+# Windows (installed app)
+set LEDGRAB_DEMO=true
+LedGrab.bat
+```
+
+Demo mode uses port **8081**, config file `config/demo_config.yaml`, and stores data in `data/demo/` (separate from production data). It can run alongside the main server.
+
 ## Architecture
 
 ```text
-wled-screen-controller/
+ledgrab/
 ├── server/                          # Python FastAPI backend
-│   ├── src/wled_controller/
+│   ├── src/ledgrab/
 │   │   ├── main.py                  # Application entry point
 │   │   ├── config.py                # YAML + env var configuration
 │   │   ├── api/
@@ -151,8 +171,6 @@ wled-screen-controller/
 │   ├── tests/                       # pytest suite
 │   ├── Dockerfile
 │   └── docker-compose.yml
-├── custom_components/               # Home Assistant integration (HACS)
-│   └── wled_screen_controller/
 ├── docs/
 │   ├── API.md                       # REST API reference
 │   └── CALIBRATION.md               # LED calibration guide
@@ -162,7 +180,7 @@ wled-screen-controller/
 
 ## Configuration
 
-Edit `server/config/default_config.yaml` or use environment variables with the `WLED_` prefix:
+Edit `server/config/default_config.yaml` or use environment variables with the `LEDGRAB_` prefix:
 
 ```yaml
 server:
@@ -180,11 +198,11 @@ storage:
 
 logging:
   format: "json"
-  file: "logs/wled_controller.log"
+  file: "logs/ledgrab.log"
   max_size_mb: 100
 ```
 
-Environment variable override example: `WLED_SERVER__PORT=9090`.
+Environment variable override example: `LEDGRAB_SERVER__PORT=9090`.
 
 ## API
 
@@ -214,9 +232,7 @@ See [docs/CALIBRATION.md](docs/CALIBRATION.md) for a step-by-step guide.
 
 ## Home Assistant
 
-Install via HACS (add as a custom repository) or manually copy `custom_components/wled_screen_controller/` into your HA config directory. The integration creates light, switch, sensor, and number entities for each configured device.
-
-See [INSTALLATION.md](INSTALLATION.md) for detailed setup instructions.
+For Home Assistant integration, see the separate [ledgrab-haos-integration](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration) repository.
 
 ## Development
 

RELEASE_NOTES.md

@@ -0,0 +1,167 @@
+## v0.7.0 (2026-05-26)
+
+A device-support release: **seven new device families**, a unified **pairing UX**,
+a brand-new **HTTP-endpoint** output type, **multi-broker MQTT + Zigbee2MQTT**
+support, a major **shutdown / data-safety** fix, and a deep architectural
+refactor pass that landed registry patterns for every dispatch hot path.
+
+### Features
+
+#### New device types
+
+- **DDP** — standalone Open-Pixel-Control-style target for Pixelblaze / ESPixelStick / xLights / Falcon endpoints, port 4048 ([8f1140a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/8f1140a))
+- **Yeelight** — Xiaomi/Yeelight bulbs and lightstrips over JSON-RPC on port 55443, SSDP discovery ([4b65005](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/4b65005))
+- **WiZ Connected** — Philips WiZ smart bulbs over UDP on port 38899, broadcast discovery ([ede627b](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ede627b))
+- **LIFX** — LIFX bulbs and lightstrips over the binary LIFX LAN protocol on port 56700 ([8f9d490](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/8f9d490))
+- **Govee LAN** — Govee Wi-Fi bulbs and ambient kits, multicast discovery (requires "LAN Control" enabled in the Govee Home app) ([887131d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/887131d))
+- **Open Pixel Control (OPC)** — Fadecandy boards, xLights/Falcon, OPC bridges, port 7890 with channel addressing ([31c6c3a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/31c6c3a))
+- **Nanoleaf** — Light Panels / Canvas / Shapes / Lines / Elements over the documented HTTP REST API on port 16021 ([426484a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/426484a))
+
+#### New output type
+
+- **HTTP endpoint output target** — POST live strip frames to any user-configured HTTP endpoint, alongside WLED / MQTT / Hue. Full editor + storage + routes ([d6cc800](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/d6cc800))
+
+#### Pairing flow
+
+- Generic **pairing UX scaffold** — 30-second SVG ring + countdown, instructions, retry/cancel. First concrete consumer is Nanoleaf; Tuya/Twinkly slot into the same shape later ([2f31680](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/2f31680))
+
+#### MQTT / Zigbee2MQTT
+
+- **Multi-broker MQTT** + new **Zigbee2MQTT light output target** sharing the HA-Light editor. Legacy single-broker YAML/env config auto-migrates to a "Default Broker" MQTTSource on startup ([530316c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/530316c))
+
+#### Editor experience
+
+- **Live preview** for color-strip sources of every type that can render without external calibration (audio, math_wave, weather, game_event, api_input, mapped, composite, processed) ([337984c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/337984c))
+- **Expanded automations** — new rule shapes + matching UI inputs + 285 lines of dispatch coverage ([3fe66d8](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/3fe66d8))
+- **Expanded value sources** — storage + schema + UI for the new value-source kinds the per-type factory refactor introduced ([737fd72](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/737fd72))
+- **Card icon picker expanded** from 44 → 120 icons across 5 new categories (weather, nature, controls, status, office) ([cdf7d94](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/cdf7d94))
+- **closeIfPristine** modal save-guard — editing an unchanged entity now silently closes the modal instead of firing a misleading "updated" toast ([f03cb30](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f03cb30))
+- New **MiniSelect** primitive for compact dropdowns that don't justify the full IconSelect grid; **IconSelect** gains a defence-in-depth XSS sanitiser on the icon channel ([9ff83bd](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/9ff83bd), [507e138](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/507e138))
+
+#### Updater
+
+- **SSRF-validated redirect chain** in the update service so a hostile mirror can't bounce the updater to a private IP. Stricter `restart.ps1` argument handling + clearer logs ([45d12b2](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/45d12b2))
+
+### Bug Fixes
+
+- **Survive PC restart** — SQLite was running WAL with `synchronous=NORMAL` and `Database.close()` was never called, so an unclean Windows shutdown rolled the DB back to the last checkpoint and silently lost recent edits. Now uses `synchronous=FULL` + `wal_autocheckpoint=100` + explicit `wal_checkpoint(TRUNCATE)` on close, and a hidden WM_QUERYENDSESSION / WM_ENDSESSION window keeps Windows from force-killing the process before the lifespan can finish ([e24f9d3](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/e24f9d3))
+- **Devices PATCH preserves URL** — PATCH-without-`url` (rename / icon-only) used to drop the address into the processor as None ([0dd8d43](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0dd8d43))
+- **HA Light brightness scale** — `_send_entity_color` was double-applying `brightness_scale` below 1 (quartered output for a half-scale) and skipping it above 1 (boost lost). Now one `clamp(max(r,g,b) * bs * vs, 0, 255)` pass with regression coverage ([ad84b60](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ad84b60))
+- **Dashboard "MODIFIED" badge** no longer fires retroactively on un-edited legacy layouts — `userModified` is now driven by actual edits, not deep-equal drift from defaults ([e4bf58d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/e4bf58d))
+- **Transport-bar uptime** repaints on `/health` response instead of waiting up to ~10 s for the next poll ([f1b0f0e](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f1b0f0e))
+- **Pre-merge device-support review pass** — `update_device` no longer double-encrypts secrets in memory; `GET /devices` strips paired-only secrets behind boolean flags; SSRF validation on every new driver; corrupt-envelope decrypt returns `""` instead of deleting the device row; `update_device` URL trim matches create; Govee discovery port-4002 collision serialised behind a module lock; Nanoleaf mDNS scan cleans up tasks on cancel; pair endpoint stops logging userinfo / exception bodies ([0e3ae78](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0e3ae78))
+- **value_source factory contract** — `_build_game_event` raises `NotImplementedError` (preserves the historical store contract) and `create_source` runs `build_source` before `_check_name_unique` so an invalid `source_type` raises the right error ([c1aa2eb](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/c1aa2eb))
+- **`utils/url_scheme` + `utils/net_classify`** were referenced but untracked on a clean checkout — server failed to start with `ModuleNotFoundError`. Now committed ([7736bc6](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/7736bc6))
+
+### Performance
+
+- **Capture hot paths vectorised** — WGC swaps per-frame ~30 MB BGRA→RGB fancy-index allocations for `cv2.cvtColor` into a 3-slot pre-allocated pool; MSS uses `screenshot.raw + cv2.cvtColor` with 256-byte change-detection; DXcam/BetterCam fixes a silent name-mangling factory leak; dominant-colour reduction is ~10× faster via packed-RGB `np.bincount` ([f184ef0](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f184ef0))
+- **Event-driven frame hand-off** — `LiveStream` gains a `frame_id` + `Condition`, consumers wait instead of polling, ring buffer grows 3 → 5 slots, `_blend_u16` uses `cv2.addWeighted`. Up to one `frame_time` of glass-to-LED latency saved at matched FPS ([ee4fa81](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ee4fa81))
+- **WLED brightness threshold** caches per-frame `np.max` keyed on frame identity instead of reducing the LED array every loop ([6e4c1b6](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/6e4c1b6))
+- **Dashboard FPS charts** now diff target ids and only recreate added/removed/detached charts (skipping the history fetch when local samples already exist), and spark SVGs are mutated in place instead of `innerHTML`-rewritten every poll. Memoised patches/devices rendering by content signature so unchanged ticks no longer restart CSS animations ([f6486f9](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f6486f9))
+
+---
+
+### Development / Internal
+
+#### Architecture audit — registry patterns everywhere
+
+- **Color-strip stream dispatch** — `ColorStripStreamManager.acquire()` and `ws_stream._create_stream()` now share a `STREAM_BUILDERS` registry keyed by source type, with import-time coverage assertion against `_SOURCE_TYPE_MAP`. CSS response builder gets the same treatment ([563cbac](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/563cbac))
+- **Value-source create / update** — `ValueSourceStore.create_source` shrinks from ~260 → ~25 lines via per-type builder/applier functions in a new `storage.value_source_factories` module ([3b8f00e](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/3b8f00e))
+- **SystemMetricsValueStream** — three parallel `if/elif` chains collapse into a `MetricSpec(name, read_psutil, read_fallback, normalize, prime)` registry in `core.processing.metric_readers` ([9f3f346](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/9f3f346))
+- **Automation engine** — per-rule-type bodies become `_handle_<kind>` methods, dispatch table built once at class-creation, unknown-type fallback logs instead of silently returning False ([98fb61d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/98fb61d))
+- **Effect renderer dispatch** — `@_effect_renderer("fire")` decorators + class-level `_RENDERERS` dict replace per-frame dict-rebuild + silent fire fallback ([97dae2c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/97dae2c))
+- **Output-target response builders** — `isinstance` ladder + silent fabricated-LED fallback replaced with `_TARGET_RESPONSE_BUILDERS` dict and a runtime `RuntimeError` for unknown subclasses ([2f15fbb](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/2f15fbb))
+- **Versioned data migrations** — replaces a naked `blob.replace(...)` migration with `storage.data_migrations.MigrationRunner` backed by a `data_migrations` audit table and atomic transactions ([563cbac](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/563cbac))
+
+#### Dedup / refactor
+
+- **Edge-to-LED kernels** in `PixelMapper` + `AdvancedPixelMapper` deduped into a shared `core.capture.edge_interpolation` module ([5fec8db](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/5fec8db))
+- **HA/Z2M `_swap_color_source`** unified behind a shared `light_target_helpers.swap_color_source` helper ([29bdacf](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/29bdacf))
+- **Single-pixel `_average_color`** lifted out of 6 LED drivers into `core.devices.pixel_reduce.average_color` ([cc87fba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/cc87fba))
+- **Static → single rename** for the color-strip source kind. Storage keeps backward-compatible serialisation ([826e680](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/826e680))
+- **Bindable types** extracted into `types/bindable.ts`; the wider `types.ts` god-module split is staged for a follow-up frontend sprint ([05f73ee](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/05f73ee))
+- **WebSocket auth** — 11 `except Exception` sites around handshake replaced with a narrow `_WS_SEND_BENIGN_EXC` tuple; receive path adds explicit observability ([ea7ee88](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ea7ee88))
+- **Backend hardening bundle** — MQTT task tracking + drain resilience, credential encryption with auto-migration, devices watcher task tracking, WLED scheme inference at boundaries, streaming-upload caps, `asyncio.gather(return_exceptions=True)` on broadcast loops, WebSocket Origin allow-list, `/docs` auth-gate ([898912f](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/898912f))
+- **Frontend infra** — inbound-event allowlist mirroring the server side, `closeIfPristine` adoption across editors, MiniSelect markup for filter pickers ([ddae571](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ddae571))
+- **PEP-604 union sweep** — `ruff --select UP007,UP045 --fix` converted ~1760 sites from `Optional[T]` / `Union[X, Y]` to `T | None` / `X | Y`. Hooks bumped to ruff v0.15.12 to recognise UP045 ([888f8fd](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/888f8fd))
+- **Typed window globals** — 59 `(window as any).foo` sites across 19 feature modules switched to typed `window.foo` against `global-types.d.ts` ([0035172](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0035172))
+- **Processing magic numbers** lifted to named module constants so tests can monkeypatch them ([d38021f](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/d38021f))
+- **`Database.ensure_open()`** — module-level singleton reopens cleanly across lifespan cycles, fixing 65 spurious `sqlite3.ProgrammingError` setup failures on Windows pytest aggregate runs ([f591e25](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f591e25))
+
+#### Tests
+
+- WLED URL scheme integration + IPv6 regression coverage ([907bdaf](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/907bdaf))
+- Lifespan reopen invariants on `Database` ([f591e25](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f591e25))
+- Hundreds of new tests covering every registry / factory / migration introduced above
+
+#### Tooling / docs
+
+- `.vex.toml` makes vex the project's primary code-search backend with auto-update + semantic embeddings ([06273ba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/06273ba))
+- `REVIEW_TODO.md` captures audit items deliberately deferred; `TODO.md` records the architecture-audit remainder ([06273ba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/06273ba), [628c6b2](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/628c6b2))
+- Locale + CLAUDE.md upkeep alongside the new features ([fd46c51](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/fd46c51), [48dbdb9](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/48dbdb9), [17684af](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/17684af), [390d2b4](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/390d2b4))
+
+---
+
+<details>
+<summary>All Commits (55)</summary>
+
+| Hash | Message |
+|------|---------|
+| [f591e25](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f591e25) | fix(storage/database): reopen connection on lifespan restart |
+| [f6486f9](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f6486f9) | perf(dashboard): diff FPS charts + cache spark SVG nodes; i18n perf strings |
+| [48dbdb9](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/48dbdb9) | docs(review-todo): check off items addressed in 2026-05-23 autonomous pass |
+| [0035172](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0035172) | refactor(types): migrate (window as any) statics to typed window globals |
+| [888f8fd](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/888f8fd) | refactor(types): PEP-604 union sweep + UP007/UP045 enforcement |
+| [ea7ee88](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ea7ee88) | refactor(api/auth): narrow WS exception catches + observability log |
+| [d38021f](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/d38021f) | refactor(processing): hot-path magic numbers -> named module constants |
+| [507e138](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/507e138) | feat(ui/icon-select): defence-in-depth XSS sanitiser on icon channel |
+| [907bdaf](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/907bdaf) | test(url-scheme): WLED route-level integration + IPv6 regression |
+| [0dd8d43](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0dd8d43) | fix(devices): preserve existing URL on PATCH-without-url |
+| [fd46c51](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/fd46c51) | docs: TODO + CLAUDE.md notes + locale keys for new features |
+| [ddae571](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ddae571) | chore(frontend-infra): inbound-event allowlist + storage/state touch-ups |
+| [898912f](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/898912f) | chore(backend): MQTT/WLED/devices/capture/utils + api routes hardening |
+| [45d12b2](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/45d12b2) | feat(update-service): SSRF-validated redirects + restart hardening |
+| [826e680](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/826e680) | refactor(color-strip): rename static -> single + frontend follow-through |
+| [737fd72](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/737fd72) | feat(value-sources): extend storage + schema + UI alongside new kinds |
+| [3fe66d8](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/3fe66d8) | feat(automations): expand automation rules + UI + engine coverage |
+| [f03cb30](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f03cb30) | feat(modal): closeIfPristine save-guard + per-editor adoption |
+| [9ff83bd](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/9ff83bd) | feat(ui): MiniSelect primitive + IconSelect XSS hardening + typed globals |
+| [d6cc800](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/d6cc800) | feat(http-endpoints): introduce HTTP endpoint output target stack |
+| [06273ba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/06273ba) | chore(tooling): vex semantic-search config + REVIEW_TODO backlog |
+| [628c6b2](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/628c6b2) | docs: capture architecture-audit remainder for follow-up sessions |
+| [2f15fbb](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/2f15fbb) | refactor(output-targets): registry + coverage assertion for response builders |
+| [c1aa2eb](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/c1aa2eb) | fix(value-source): preserve store contract for game_event + error precedence |
+| [3b8f00e](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/3b8f00e) | refactor(value-source): per-type factories for create / update dispatch |
+| [05f73ee](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/05f73ee) | refactor(types): extract bindable primitives into types/bindable.ts (H6 partial) |
+| [9f3f346](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/9f3f346) | refactor(value-source): MetricSpec registry for SystemMetricsValueStream |
+| [98fb61d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/98fb61d) | refactor(automations): rule dispatch via class-level handler table |
+| [5fec8db](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/5fec8db) | refactor(capture): lift duplicated edge-to-LED kernels into shared module |
+| [97dae2c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/97dae2c) | refactor(processing): replace inline effect dispatch with @_effect_renderer registry |
+| [29bdacf](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/29bdacf) | refactor(processing): dedupe HA/Z2M _swap_color_source via shared helper |
+| [563cbac](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/563cbac) | refactor(storage,processing): kind registries + versioned data migrations |
+| [e24f9d3](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/e24f9d3) | fix(shutdown): survive PC restart with WAL fsync + Win32 session-end guard |
+| [e4bf58d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/e4bf58d) | fix(dashboard): stop showing perpetual MODIFIED for un-edited legacy layouts |
+| [f1b0f0e](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f1b0f0e) | fix(ui): repaint transport-bar uptime as soon as /health responds |
+| [17684af](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/17684af) | docs: record review-fix pass in TODO.md |
+| [0e3ae78](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/0e3ae78) | fix(devices): address pre-merge review findings |
+| [7736bc6](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/7736bc6) | fix(utils): commit url_scheme + net_classify dependencies |
+| [390d2b4](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/390d2b4) | docs: mark expand-device-support branch ready for merge |
+| [cc87fba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/cc87fba) | refactor(devices): extract _average_color to pixel_reduce |
+| [426484a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/426484a) | feat(devices): Nanoleaf OpenAPI target type + first pair-flow user |
+| [2f31680](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/2f31680) | feat(devices): pairing-UX scaffold (Phase 2) |
+| [31c6c3a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/31c6c3a) | feat(devices): Open Pixel Control (OPC) target type |
+| [887131d](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/887131d) | feat(devices): Govee LAN target type |
+| [8f9d490](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/8f9d490) | feat(devices): LIFX LAN target type |
+| [ede627b](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ede627b) | feat(devices): WiZ Connected LAN target type |
+| [4b65005](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/4b65005) | feat(devices): Yeelight LAN target type |
+| [8f1140a](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/8f1140a) | feat(devices): standalone DDP target type |
+| [337984c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/337984c) | feat(color-strips): in-editor live preview for all viable source types |
+| [530316c](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/530316c) | feat(mqtt): multi-broker MQTT + Zigbee2MQTT light target |
+| [6e4c1b6](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/6e4c1b6) | perf(wled): cache per-frame max-pixel for brightness threshold |
+| [ee4fa81](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ee4fa81) | perf(processing): event-driven frame hand-off and scheduling fixes |
+| [f184ef0](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f184ef0) | perf(capture): vectorize hot paths and fix engine bugs |
+| [ad84b60](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/ad84b60) | fix(ha-light): apply brightness_scale once and respect boost multipliers |
+| [cdf7d94](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/cdf7d94) | feat(ui): expand card icon picker (44 -> 120 icons, +5 categories) |
+
+</details>

REVIEW_TODO.md

@@ -0,0 +1,180 @@
+# Production Review — Remaining Items
+
+Output of the multi-agent production review (security / Python / TypeScript /
+performance / architecture / code-quality). Each entry below is something
+the original audit flagged and the autonomous hardening pass deliberately
+did **not** address — either because it needs design input, profiling
+validation, or a multi-day refactor that should land in its own session.
+
+The hardening pass landed everything else: see git log between `master` and
+the head of the review branch for the applied changes (URL-scheme +
+malicious-input rejection, IconSelect XSS escape, MiniSelect for forbidden
+plain `<select>`s, WebSocket Origin allow-list, /docs auth-gate, security
+headers middleware, streaming upload size caps, fire-and-forget task
+tracking + drain resilience in MQTT runtime, discovery_watcher task
+tracking, asyncio.gather return_exceptions, secret_box encryption for MQTT
+/ Hue / Govee credentials with auto-migration, SSRF-validated update
+redirects, single source of truth for IP classification in
+`utils/net_classify.py`, allowlist + parity test for inbound WS events,
+typed `Window` globals, and more).
+
+## Items completed in the follow-up autonomous pass (2026-05-23)
+
+- [x] **devices.py PATCH-without-url processor desync** — `update_device`
+      now falls back to `existing.url` so a rename / icon-only edit
+      always tells the processor the current address.
+- [x] **WLED scheme integration test** on `/api/v1/devices` — covers
+      bare IPv4 (`http://`), public hostname (`https://`), and trailing-slash
+      normalisation; lives in `tests/api/routes/test_devices_routes.py`.
+- [x] **IPv6 regression test** — `tests/test_url_scheme.py` now pins
+      public IPv6 → `https://`, ULA → `http://`, and documents the
+      Python-`ipaddress` documentation-prefix classification quirk.
+- [x] **IconSelect XSS audit + defence-in-depth** — every caller
+      audited (all feed `icon` from constants or lookup tables); added
+      `sanitiseIcon` that rejects `<script>`, `javascript:`, `on*=`,
+      `<iframe>`, `<embed>`, `<object>` and warns to the console.
+- [x] **`Optional[T]` → `T | None` (PEP 604)** — 55 sites cleaned via
+      `ruff --fix UP007`. The remaining `Union[…]` aliases for
+      pixel/colour/device-config typing converted by hand. `UP007` now
+      lives in `pyproject.toml` so the rule fires on new code.
+- [x] **Hot-path magic numbers → named constants** — `processed_stream`
+      gains `_FILTER_RECHECK_EVERY_N_FRAMES`; `wled_target_processor`
+      gains `_SKIP_REPOLL_SLEEP_SECONDS`, `_DIAGNOSTICS_REPORT_INTERVAL_SECONDS`,
+      `_CSPT_RECHECK_EVERY_N_ITERATIONS`.
+- [x] **`api/auth.py` `except Exception` tightening** — every WS send /
+      close site is now `except _WS_SEND_BENIGN_EXC` (a narrow tuple of
+      WebSocketDisconnect / RuntimeError / ConnectionError / OSError).
+      The auth-receive path catches the same set plus a final
+      `logger.exception` catch-all for observability on truly unexpected
+      shapes.
+- [x] **`(window as any)` cleanup** — 59 static-property accesses
+      migrated to typed `window.<name>` against `global-types.d.ts`. The
+      remaining 7 sites use dynamic string indexing (`window[fnName]`)
+      and intentionally keep the cast (documented in the typedef file).
+
+---
+
+## Architecture refactors (multi-day — own session)
+
+- [ ] **Split `core/processing/value_stream.py`** (1856 LOC, 14 stream classes)
+      into a `value_streams/` package. Each value-stream type gets its own
+      file ≤300 LOC; `manager.py` holds `ValueStreamManager`.
+- [ ] **Split `storage/color_strip_source.py`** (1841 LOC, 18 source kinds)
+      into a `color_strip_sources/` package mirroring `value_streams/`.
+- [ ] **Frontend file splits** — `graph-editor.ts` (2707), `streams.ts`
+      (2335), `value-sources.ts` (1889), `types.ts` (1062). Highest-churn
+      modules; mixed UI / state / network responsibilities.
+- [ ] **Layering reversal**: introduce a neutral `domain/` package and move
+      shared DTOs (`FilterInstance`, `CalibrationConfig`, etc.) into it so
+      `storage/` no longer imports `core/`. Eliminates 7+ layering
+      violations and the lazy-import hacks used to break the resulting
+      circulars.
+- [ ] **`main.py` boot refactor** — extract import-time side effects into
+      `bootstrap.py` + `create_app()` factory. `lifespan()` becomes the
+      single place that wires stores and managers.
+- [ ] **DI consolidation** — replace `api/dependencies.py` getter sprawl
+      (30+ `get_*()` functions reading a process-global `_deps` dict) with
+      a single typed `get_container()` dependency. Makes test-overrides
+      trivial; ban direct getter calls in handler bodies.
+- [ ] **Exception hierarchy** — define `ledgrab/errors.py` (`LedGrabError`,
+      `NotFoundError`, `ValidationError`, `RemoteUnavailableError`,
+      `SSRFBlockedError`). Move HTTP translation into a FastAPI exception
+      handler. Stop raising `HTTPException` from `utils/safe_source.py`.
+- [ ] **Lazy-import audit** — 289 in-function `from ledgrab.*` imports.
+      Specifically `core/processing/daylight_settings.py` imports
+      `api.dependencies` (core → api inversion). Pass the database in via
+      the constructor instead of service-locator lookup.
+
+## Performance (profile before applying)
+
+- [ ] **`composite_stream.py` blend modes** — pre-allocate scratch buffers
+      in `_blend_override / overlay / hard_light / soft_light / difference
+      / exclusion`. Each currently allocates per frame (`mul`, `scr`,
+      `blended`, `np.where(...)`). At 100 LEDs × 30 fps × N layers this
+      adds up.
+- [ ] **`mapped_stream` / `composite_stream` zone resize** — replace the
+      per-channel `np.interp` calls with a cached `floor/ceil/frac` LUT
+      (same trick as `wled_target_processor._fit_to_device`) or a single
+      `cv2.resize` call on the (N,3) array. `np.interp` allocates a new
+      `float64` array per channel per frame even on cache-hit.
+- [ ] **`processed_stream._processing_loop`** — add ping-pong output
+      buffers and pass them as `out=` to filter `process_strip()` calls.
+      Today every filter that returns a fresh allocation costs us a copy
+      per frame. Also: the loop uses `time.sleep` instead of an
+      event-driven wait on the input stream — input updates faster than
+      30 fps see up to `frame_time` of latency.
+- [ ] **`mqtt_client.py` `send_pixels`** — add a binary publish path (or
+      at minimum cache the outer dict skeleton). Today every frame
+      `pixels.tolist()` + `json.dumps` for ~300 LEDs × 30 fps × N devices.
+- [ ] **Frontend `static/js/features/color-strips/test.ts`** — cache
+      `ImageData` per canvas (`canvas._imageData`); only re-create on
+      dimension change; use a `Uint32Array` view to copy pixels in one
+      loop instead of the per-pixel JS loop. Border-overlay rebuild on
+      every frame should also be debounced to dimension changes only.
+- [ ] **`ws_stream.py` composite branch** — pre-allocate a `bytearray`
+      sized to the largest frame and write into slices instead of
+      `b"".join(tobytes()) per layer` every iteration. Same anti-pattern
+      in `wled_target_processor._broadcast_led_preview`.
+- [ ] **Preview broadcast slow-client guard** — `asyncio.gather` over
+      preview clients waits for the slowest. Move to `asyncio.wait` with a
+      timeout and drop slow clients, or fire-and-forget with a
+      `ws.application_state` filter.
+
+## Security (deferred — non-trivial or design-sensitive)
+
+- [ ] **Content-Security-Policy header** — would need careful tuning
+      because the UI uses inline event handlers / Jinja templates.
+      Mis-set CSP would break the app silently. Defer until templates can
+      move to event-delegated handlers, then add a strict policy.
+- [x] **`api/auth.py` exception specificity** — done in the 2026-05-23
+      pass; see top of file.
+- [ ] **Hue bridge cert pinning** — `httpx.AsyncClient(verify=False)` for
+      Hue bridge (self-signed cert by design). Should record the
+      certificate fingerprint at pairing time and pin it on subsequent
+      requests; otherwise an on-path attacker can MITM the bridge.
+
+## Mechanical / code-quality (low risk, high line-count)
+
+- [ ] **i18n parity** — confirmed **328** keys missing in `ru.json` and
+      **325** missing in `zh.json` against the canonical English file.
+      Translation work — needs a native speaker, not a machine-translation
+      pass. Run `py scripts/diff_locale_keys.py` (or copy the diff block
+      out of the 2026-05-23 pass log) to get the exact key list.
+- [x] **`Optional[T]` → `T | None`** — done; `UP007` now enforced via
+      `pyproject.toml` so the rule prevents regressions.
+- [ ] **Hot-path `logger.error(f"...")` → `logger.error("... %s", e)`**
+      lazy-eval — 658 sites flagged by `ruff --select G004`. Deferred
+      because it is genuinely cosmetic at ERROR level (always emitted)
+      and the cumulative cost is negligible. Worth doing if/when ruff
+      gains a safe autofix, or as a Codemod in a dedicated session.
+- [x] **Remaining `(window as any)` sites** — 59 migrated to typed
+      `window.<name>` access; the 7 surviving sites use dynamic string
+      indexing and are documented as the legitimate exception.
+- [x] **Magic numbers → named constants** — done; see `processed_stream`
+      and `wled_target_processor` constants at the top of each module.
+- [ ] **Standardise `from __future__ import annotations`** — partially
+      mooted by the UP007 cleanup. Files that previously relied on
+      `Optional`/`Union` no longer need the future import; the few that
+      already use `__future__` keep it for forward-reference convenience.
+      A blanket policy would still help — leave as a stylistic followup.
+
+## Test gaps
+
+- [x] **Route-level integration test** for the WLED scheme inference —
+      done; covers create + update in `tests/api/routes/test_devices_routes.py::TestWLEDSchemeInference`.
+- [x] **IPv6 public address regression** — done; pinned in
+      `tests/test_url_scheme.py` for both bracketless and bracketed forms.
+
+## Pre-existing issues surfaced during the audit (not in our diff)
+
+These were flagged by the auditors but predate the review session — kept
+here as a future-work backlog:
+
+- [x] **`icon-select.ts:_buildGrid` `item.icon` is interpolated raw** —
+      audited; all callers pass project-owned literals or table-lookup
+      results. Added a runtime sanitiser as defence-in-depth.
+- [x] **`devices.py` `manager.update_device_info(device_url=update_data.url)`**
+      None-on-PATCH path — fixed; now falls back to `existing.url`.
+- [ ] **`asyncio.gather` over uncapped client lists** in preview broadcasts
+      — slow clients block the loop. Already noted under Performance
+      above; pre-existing.

TODO-css-improvements.md

@@ -1,114 +0,0 @@
-# TODO
-
-## IMPORTANT: Remove WLED naming throughout the app
-
-- [ ] Rename all references to "WLED" in user-facing strings, class names, module names, config keys, file paths, and documentation
-- [ ] The app is **LedGrab** — not tied to WLED specifically. WLED is just one of many supported output protocols
-- [ ] Audit: i18n keys, page titles, tray labels, installer text, pyproject.toml description, README, CLAUDE.md, context files, API docs
-- [ ] Rename `wled_controller` package → decide on new package name (e.g. `ledgrab`)
-- [ ] Update import paths, entry points, config references, build scripts, Docker, CI/CD
-- [ ] **Migration required** if renaming storage paths or config keys (see data migration policy in CLAUDE.md)
-
----
-
-## Donation / Open-Source Banner
-
-- [ ] Add a persistent but dismissible banner or notification in the dashboard UI informing users that the project is open-source and under active development, and that donations are highly appreciated
-- [ ] Include a link to the donation page (GitHub Sponsors, Ko-fi, or similar — decide on platform)
-- [ ] Remember dismissal in localStorage so it doesn't reappear every session
-- [ ] Add i18n keys for the banner text (`en.json`, `ru.json`, `zh.json`)
-
----
-
-# Color Strip Source Improvements
-
-## New Source Types
-
-- [x] **`weather`** — Weather-reactive ambient: maps weather conditions (rain, snow, clear, storm) to colors/animations via API
-- [ ] **`music_sync`** — Beat-synced patterns: BPM detection, energy envelope, drop detection (higher-level than raw `audio`)
-- [ ] **`math_wave`** — Mathematical wave generator: user-defined sine/triangle/sawtooth expressions, superposition
-- [ ] **`text_scroll`** — Scrolling text marquee: bitmap font rendering, static text or RSS/API data source *(delayed)*
-
-### Discuss: `home_assistant`
-
-Need to research HAOS communication options first (WebSocket API, REST API, MQTT, etc.) before deciding scope.
-
-### Deferred
-
-- `image` — Static image sampler *(not now)*
-- `clock` — Time display *(not now)*
-
-## Improvements to Existing Sources
-
-### `effect` (now 12 types)
-
-- [x] Add effects: rain, comet, bouncing ball, fireworks, sparkle rain, lava lamp, wave interference
-- [x] Custom palette support: user-defined [[pos,R,G,B],...] stops via JSON textarea
-
-### `gradient`
-
-- [x] Noise-perturbed gradient: value noise displacement on stop positions (`noise_perturb` animation type)
-- [x] Gradient hue rotation: `hue_rotate` animation type — preserves S/V, rotates H
-- [x] Easing functions between stops: linear, ease_in_out (smoothstep), step, cubic
-
-### `audio`
-
-- [x] New audio source type: band extractor (bass/mid/treble split) — responsibility of audio source layer, not CSS
-- [ ] Peak hold indicator: global option on audio source (not per-mode), configurable decay time
-
-### `daylight`
-
-- [x] Longitude support for accurate solar position (NOAA solar equations)
-- [x] Season awareness (day-of-year drives sunrise/sunset via solar declination)
-
-### `candlelight`
-
-- [x] Wind simulation: correlated flicker bursts across all candles (wind_strength 0.0-2.0)
-- [x] Candle type presets: taper (steady), votive (flickery), bonfire (chaotic) — applied at render time
-- [x] Wax drip effect: localized brightness dips with fade-in/fade-out recovery
-
-### `composite`
-
-- [ ] Allow nested composites (with cycle detection)
-- [x] More blend modes: overlay, soft light, hard light, difference, exclusion
-- [x] Per-layer LED range masks (optional start/end/reverse on each composite layer)
-
-### `notification`
-
-- [x] Chase effect (light bounces across strip with glowing tail)
-- [x] Gradient flash (bright center fades to edges, exponential decay)
-- [x] Queue priority levels (color_override = high priority, interrupts current)
-
-### `api_input`
-
-- [ ] Crossfade transition when new data arrives
-- [ ] Interpolation when incoming LED count differs from strip count
-- [ ] Last-write-wins from any client (no multi-source blending)
-
-## Architectural / Pipeline
-
-### Processing Templates (CSPT)
-
-- [x] HSL shift filter (hue rotation + lightness adjustment)
-- [x] ~~Color temperature filter~~ — already exists as `color_correction`
-- [x] Contrast filter
-- [x] ~~Saturation filter~~ — already exists
-- [x] ~~Pixelation filter~~ — already exists as `pixelate`
-- [x] Temporal blur filter (blend frames over time)
-
-### Transition Engine
-
-Needs deeper design discussion. Likely a new entity type `ColorStripSourceTransition` that defines how source switches happen (crossfade, wipe, etc.). Interacts with automations when they switch a target's active source.
-
-### Deferred
-
-- Global BPM sync *(not sure)*
-- Recording/playback *(not now)*
-- Source preview in editor modal *(not needed — overlay preview on devices is sufficient)*
-
----
-
-## Remaining Open Discussion
-
-1. **`home_assistant` source** — Need to research HAOS communication protocols first
-2. **Transition engine** — Design as `ColorStripSourceTransition` entity: what transition types? (crossfade, wipe, dissolve?) How does a target reference its transition config? How do automations trigger it?

TODO-release.md

@@ -0,0 +1,54 @@
+# TODO
+
+## Donation / Open-Source Banner
+
+- [x] Add a persistent but dismissible banner or notification in the dashboard UI informing users that the project is open-source and under active development, and that donations are highly appreciated
+- [x] Include a link to the donation page (GitHub Sponsors, Ko-fi, or similar — decide on platform)
+- [x] Remember dismissal in localStorage so it doesn't reappear every session
+- [x] Add i18n keys for the banner text (`en.json`, `ru.json`, `zh.json`)
+- [ ] Configure `DONATE_URL` and `REPO_URL` constants in `donation.ts` once platform is chosen
+
+## Android Signing Secrets (Gitea)
+
+The CI workflow `build-android.yml` produces a signed release APK **only** when all four secrets below are configured in Gitea → Settings → Secrets. When any one is missing, the "Guard release tag against missing keystore" step hard-fails a `v*` tag build — previously we silently shipped a debug-signed APK labeled as release.
+
+| Secret | Contents |
+| --- | --- |
+| `ANDROID_KEYSTORE_BASE64` | Output of `base64 -w0 release.jks` — the whole keystore as one line |
+| `ANDROID_KEYSTORE_PASSWORD` | Keystore password (the `-storepass` passed to `keytool`) |
+| `ANDROID_KEY_ALIAS` | Key alias (e.g. `ledgrab-release`) |
+| `ANDROID_KEY_PASSWORD` | Key password (can be the same as keystore password) |
+
+### Generate the keystore (one-time, ~2 min)
+
+```bash
+keytool -genkeypair -v \
+  -storetype JKS \
+  -keystore release.jks \
+  -alias ledgrab-release \
+  -keyalg RSA -keysize 4096 \
+  -validity 9125 \
+  -dname "CN=LedGrab, O=Dolgolyov, C=BY"
+
+base64 -w0 release.jks > release.jks.b64    # Linux / Git Bash
+# Windows alternative:
+#   certutil -encode release.jks release.jks.b64
+#   (strip the -----BEGIN/END CERTIFICATE----- header/footer lines)
+```
+
+### Critical — back up `release.jks` outside the repo
+
+- 1Password attachment, encrypted USB stick, or printed hex + password written down somewhere physical.
+- Losing the keystore = every existing sideloaded install is permanently unable to upgrade. The only workaround is uninstall-then-reinstall, which wipes user data.
+- The `release.jks` file itself must **never** be committed to git. Only the base64 string lives in Gitea secrets.
+
+### Why it matters even without Play Store
+
+Android's package manager refuses to install an upgrade whose signature differs from the currently-installed APK's signature — enforced by the OS, not Play. So once users install a build signed by key X, every future build they can upgrade to must also be signed by key X.
+
+### Current state
+
+- [ ] Generate `release.jks` with `keytool` (above) and back it up
+- [ ] Upload the four secrets to Gitea
+- [ ] Tag a throwaway `v0.4.1-test` to verify signed release APK is produced (then delete the tag + release)
+- [ ] Note: any existing `v0.4.0` debug-signed install cannot upgrade to a release-signed v0.4.1 — users must uninstall first

android/.gitignore

@@ -0,0 +1,20 @@
+*.iml
+.gradle
+/local.properties
+/.idea
+.DS_Store
+/build
+/app/build
+/captures
+.externalNativeBuild
+.cxx
+local.properties
+
+# Chaquopy build cache
+.build-cache/
+
+# Python source junction (points at ../server/src/ledgrab — do not commit)
+/app/src/main/python/ledgrab
+
+# Signing keystore decoded from CI secrets
+/keystore/

android/app/build.gradle.kts

@@ -0,0 +1,183 @@
+import java.util.concurrent.TimeUnit
+
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("com.chaquo.python")
+}
+
+// Derive versionCode from git commit count so sideload/Play upgrades
+// always see a strictly-greater value without anyone remembering to
+// bump by hand.  ANDROID_VERSION_CODE env var wins for CI pipelines
+// that prefer explicit values; fallback is `1` when neither is
+// available (e.g. building from a tarball with no .git).
+val ledgrabVersionCode: Int = run {
+    System.getenv("ANDROID_VERSION_CODE")?.toIntOrNull()?.let { return@run it }
+    try {
+        val process = ProcessBuilder("git", "rev-list", "--count", "HEAD")
+            .directory(rootDir)
+            .redirectErrorStream(true)
+            .start()
+        if (process.waitFor(5, TimeUnit.SECONDS) && process.exitValue() == 0) {
+            process.inputStream.bufferedReader().readText().trim().toIntOrNull() ?: 1
+        } else {
+            1
+        }
+    } catch (_: Exception) {
+        1
+    }
+}
+
+android {
+    namespace = "com.ledgrab.android"
+    compileSdk = 34
+
+    defaultConfig {
+        applicationId = "com.ledgrab.android"
+        minSdk = 24          // Android 7.0 — covers nearly all TV boxes
+        targetSdk = 34
+        // Derived from git commit count (or ANDROID_VERSION_CODE env var
+        // in CI).  See ledgrabVersionCode above.  Was stuck at 1 before —
+        // sideload updates silently refused to install.
+        versionCode = ledgrabVersionCode
+        versionName = "0.7.0"
+
+        ndk {
+            // All three ABIs: arm64-v8a (real TV hardware), x86_64 (modern
+            // emulators), x86 (legacy emulators). Wheels in android/wheels/
+            // must be kept in sync — see build-scripts/build-pydantic-core.sh.
+            abiFilters += listOf("arm64-v8a", "x86_64", "x86")
+        }
+    }
+
+    // Per-ABI APK splits — reduces download size by ~60% vs universal APK.
+    // Each split contains only one native ABI's shared libraries + wheels.
+    splits {
+        abi {
+            isEnable = true
+            reset()
+            include("arm64-v8a", "x86_64", "x86")
+            isUniversalApk = true  // also produce a fat APK for sideloading
+        }
+    }
+
+    // Signing config from env vars (CI) — only registered when all four are set.
+    // Local release builds fall back to the debug signing config.
+    val ciKeystorePath = System.getenv("ANDROID_KEYSTORE_PATH")
+    val ciKeystorePassword = System.getenv("ANDROID_KEYSTORE_PASSWORD")
+    val ciKeyAlias = System.getenv("ANDROID_KEY_ALIAS")
+    val ciKeyPassword = System.getenv("ANDROID_KEY_PASSWORD")
+    val hasCiSigning = listOf(ciKeystorePath, ciKeystorePassword, ciKeyAlias, ciKeyPassword)
+        .all { !it.isNullOrBlank() } && file(ciKeystorePath!!).exists()
+
+    signingConfigs {
+        if (hasCiSigning) {
+            create("release") {
+                storeFile = file(ciKeystorePath!!)
+                storePassword = ciKeystorePassword
+                keyAlias = ciKeyAlias
+                keyPassword = ciKeyPassword
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            // TODO(minify): keep R8 disabled until Chaquopy reflection is
+            // verified end-to-end. Chaquopy resolves Kotlin classes & static
+            // methods (PythonBridge, UsbSerialBridge, Root) by name from
+            // Python via PyObject — silent stripping breaks the app at
+            // runtime, after release. proguard-rules.pro contains keep
+            // rules covering the known entry points, but until we have
+            // a release smoke test that exercises every PyObject path we
+            // do NOT ship a minified release.
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+            signingConfig = if (hasCiSigning) {
+                signingConfigs.getByName("release")
+            } else {
+                signingConfigs.getByName("debug")
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+chaquopy {
+    defaultConfig {
+        version = "3.11"
+
+        pip {
+            // Pre-built wheels directory (for pydantic-core etc.) as an
+            // absolute file:// URI with forward slashes. Pip requires
+            // exactly three slashes after `file:` for an empty-host local
+            // path; the path-normalization differs by platform:
+            //   Windows: absolute path is "C:/..."  → prefix "file:///"
+            //   Linux:   absolute path is "/..."    → prefix "file://"
+            // Using a fixed "file:///" prefix on both made CI produce
+            // "file:////workspace/…", which pip rejects as non-local.
+            val wheelsPath = rootDir.absolutePath.replace("\\", "/")
+            val wheelsUrlPrefix = if (wheelsPath.startsWith("/")) "file://" else "file:///"
+            options("--find-links", "$wheelsUrlPrefix$wheelsPath/wheels/")
+
+            // ── Android-compatible dependencies ─────────────────
+            // Listed explicitly because pyproject.toml includes
+            // desktop-only packages with no Android wheels.
+            // See CLAUDE.md "Android Dependency Sync" for policy.
+            install("fastapi")
+            install("uvicorn")           // without [standard] — no uvloop/httptools
+            install("httpx")
+            install("numpy")
+            install("pydantic")          // needs pydantic-core wheel in wheels/
+            install("pydantic-settings")
+            install("PyYAML")
+            install("structlog")
+            install("python-json-logger")
+            install("python-dateutil")
+            install("python-multipart")
+            install("jinja2")
+            install("zeroconf")
+            install("aiomqtt")
+            install("openrgb-python")
+            // opencv-python-headless: no cp311 Android wheel on Chaquopy.
+            // LedGrab's cv2 usage is guarded with try/except ImportError
+            // and falls back to numpy/Pillow alternatives on Android.
+            install("Pillow")
+            install("websockets")
+            install("cryptography")     // AES-GCM secret-box for HA/MQTT credentials
+        }
+    }
+}
+
+// LedGrab Python source is included via a directory junction:
+//   android/app/src/main/python/ledgrab -> server/src/ledgrab
+// This is the standard Chaquopy way to include local Python packages.
+// Create the junction (run from repo root, no admin needed):
+//   cmd /c "mklink /J android\app\src\main\python\ledgrab server\src\ledgrab"
+
+
+dependencies {
+    implementation("androidx.core:core-ktx:1.13.1")
+    implementation("androidx.appcompat:appcompat:1.7.0")
+    implementation("androidx.leanback:leanback:1.0.0")
+    implementation("com.google.android.material:material:1.12.0")
+    implementation("androidx.lifecycle:lifecycle-service:2.8.7")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
+    // QR code generation for displaying server URL on TV
+    implementation("com.google.zxing:core:3.5.3")
+    // USB-serial drivers (CH340, CP2102, FTDI, Prolific, CDC-ACM) for
+    // driving Adalight/AmbiLED controllers plugged into Android TV boxes.
+    implementation("com.github.mik3y:usb-serial-for-android:3.8.1")
+}

android/app/proguard-rules.pro

@@ -0,0 +1,27 @@
+# LedGrab ProGuard / R8 rules.
+#
+# IMPORTANT: Chaquopy resolves Java/Kotlin classes and static methods by
+# name from Python (e.g. UsbSerialBridge.INSTANCE.listDevices()) via
+# reflection. Anything reachable through PyObject must be kept by name
+# or the release build will throw NoSuchMethod / ClassNotFound at
+# runtime — silently, only on the user's device.
+#
+# Keep ALL of com.ledgrab.android.* members for safety. The app is
+# small enough that the size win from stripping these isn't worth the
+# fragility.
+-keep class com.ledgrab.android.** { *; }
+
+# Chaquopy runtime itself.
+-keep class com.chaquo.python.** { *; }
+-dontwarn com.chaquo.python.**
+
+# usb-serial-for-android — driver classes are loaded via the prober's
+# default device-id list, which uses reflection in some chip drivers.
+-keep class com.hoho.android.usbserial.driver.** { *; }
+-dontwarn com.hoho.android.usbserial.**
+
+# Kotlin coroutines — keep the debug agent off and the metadata intact.
+-dontwarn kotlinx.coroutines.**
+
+# Standard Android best-practice keeps.
+-keepattributes Signature, InnerClasses, EnclosingMethod, *Annotation*

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- BLE scanning and connecting — API ≥31 uses granular permissions;
+         older releases need BLUETOOTH + ACCESS_FINE_LOCATION for scanning.
+         neverForLocation avoids the location permission dialog on API 31+. -->
+    <uses-permission android:name="android.permission.BLUETOOTH"
+        android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
+        android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
+        android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation"
+        tools:targetApi="s" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+
+    <!-- BLE hardware — required=false so non-BT boxes still install. -->
+    <uses-feature
+        android:name="android.hardware.bluetooth_le"
+        android:required="false" />
+
+    <!-- Network access for WLED HTTP/UDP, web UI, MQTT -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+
+    <!-- MediaProjection requires a foreground service -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+
+    <!-- POST_NOTIFICATIONS for Android 13+ foreground service notification -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <!-- Autostart on boot — BootReceiver spawns CaptureService in root
+         mode so capture resumes without the user touching the remote. -->
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <!-- Exempt from Doze/App Standby so the FG service isn't killed
+         overnight on phones; essentially a no-op on TV boxes. -->
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+    <!-- Optional wake lock for sustained-performance boxes that aggressively
+         sleep the CPU with the display off. -->
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+    <!-- Android TV declarations -->
+    <uses-feature
+        android:name="android.software.leanback"
+        android:required="true" />
+    <uses-feature
+        android:name="android.hardware.touchscreen"
+        android:required="false" />
+
+    <!-- USB host — for USB-to-TTL adapters driving Adalight/AmbiLED
+         controllers. required=false so phones without USB host still install. -->
+    <uses-feature
+        android:name="android.hardware.usb.host"
+        android:required="false" />
+
+    <application
+        android:name=".LedGrabApp"
+        android:allowBackup="false"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:banner="@drawable/ic_launcher"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:theme="@style/Theme.LedGrab">
+
+        <!-- TV launcher activity -->
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <!-- Foreground service for screen capture + Python server -->
+        <service
+            android:name=".CaptureService"
+            android:foregroundServiceType="mediaProjection"
+            android:exported="false" />
+
+        <!-- Autostart — fires on device boot (and package replace).
+             On rooted devices, launches CaptureService directly so capture
+             resumes without the user tapping Start. Unrooted devices are
+             no-op because MediaProjection consent cannot be bypassed. -->
+        <receiver
+            android:name=".BootReceiver"
+            android:exported="true"
+            android:enabled="true">
+            <intent-filter>
+                <action android:name="android.intent.action.BOOT_COMPLETED" />
+                <action android:name="android.intent.action.LOCKED_BOOT_COMPLETED" />
+                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
+            </intent-filter>
+        </receiver>
+    </application>
+
+</manifest>

android/app/src/main/java/com/ledgrab/android/AutostartPrefs.kt

@@ -0,0 +1,26 @@
+package com.ledgrab.android
+
+import android.content.Context
+
+/**
+ * Thin SharedPreferences wrapper for the boot-autostart toggle.
+ *
+ * Default is `true`: [BootReceiver] still bails out when the device
+ * isn't rooted, so a true default is safe — it only takes effect on
+ * boxes where we can actually honor it silently.
+ */
+class AutostartPrefs(context: Context) {
+
+    private val prefs = context.applicationContext
+        .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    var isEnabled: Boolean
+        get() = prefs.getBoolean(KEY_ENABLED, DEFAULT_ENABLED)
+        set(value) { prefs.edit().putBoolean(KEY_ENABLED, value).apply() }
+
+    companion object {
+        private const val PREFS_NAME = "ledgrab_autostart"
+        private const val KEY_ENABLED = "autostart_enabled"
+        private const val DEFAULT_ENABLED = true
+    }
+}

android/app/src/main/java/com/ledgrab/android/BleBridge.kt

@@ -0,0 +1,288 @@
+package com.ledgrab.android
+
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothProfile
+import android.bluetooth.le.ScanCallback
+import android.bluetooth.le.ScanResult
+import android.content.Context
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import java.util.Collections
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicInteger
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.TimeoutCancellationException
+
+/**
+ * Android BLE bridge exposed to the Python server via Chaquopy.
+ *
+ * Wraps the Android BluetoothGatt / BluetoothLeScanner APIs into
+ * synchronous, blocking calls that can be safely invoked from
+ * a Python thread (Chaquopy proxy threads are real OS threads).
+ *
+ * All GATT callbacks run on a private [HandlerThread] so they don't
+ * block the main looper.  [runBlocking] is used to bridge callback
+ * completions back to the calling Python thread.
+ *
+ * Python callers access the singleton via
+ *   `BleBridge.INSTANCE.scan()` etc. — see
+ *   `server/src/ledgrab/core/devices/android_ble_transport.py`.
+ */
+object BleBridge {
+    private const val TAG = "BleBridge"
+    private const val CONNECT_TIMEOUT_MS = 18_000L // connect + service discovery
+    private const val WRITE_TIMEOUT_MS = 5_000L
+
+    @Volatile private var appContext: Context? = null
+
+    private val handleSeq = AtomicInteger(1)
+
+    // Dedicated looper thread so BLE callbacks don't land on the main thread.
+    private val bleHandlerThread = HandlerThread("LedGrab-BLE").also { it.start() }
+    private val bleHandler = Handler(bleHandlerThread.looper)
+
+    private data class GattHandle(
+        val gatt: BluetoothGatt,
+        val writeChar: BluetoothGattCharacteristic,
+    )
+
+    private val handles = ConcurrentHashMap<Int, GattHandle>()
+
+    // Write completion futures, keyed by handle.  Only populated for
+    // WRITE_TYPE_DEFAULT (with-response) writes.
+    private val pendingWrites = ConcurrentHashMap<Int, CompletableDeferred<Boolean>>()
+
+    /** Called once from [LedGrabApp.onCreate] to bind the application context. */
+    @JvmStatic
+    fun init(context: Context) {
+        appContext = context.applicationContext
+    }
+
+    private fun ctx(): Context =
+        appContext ?: error("BleBridge.init() not called — app context unavailable")
+
+    private fun adapter() =
+        ctx().getSystemService(BluetoothManager::class.java)?.adapter
+
+    // ─── Public API ──────────────────────────────────────────────────────────
+
+    /**
+     * Scan for BLE peripherals for [timeoutMs] milliseconds.
+     *
+     * Returns a list of `"address|name|rssi"` strings.  Addresses are
+     * deduplicated — only the last-seen RSSI for each address is kept.
+     * Returns an empty list if Bluetooth is off or the permission is denied.
+     */
+    @JvmStatic
+    @JvmOverloads
+    fun scan(timeoutMs: Long = 4_000L): List<String> {
+        val adapter = adapter() ?: return emptyList()
+        if (!adapter.isEnabled) return emptyList()
+        val scanner = try { adapter.bluetoothLeScanner } catch (_: SecurityException) { null }
+            ?: return emptyList()
+
+        val seen = Collections.synchronizedMap(LinkedHashMap<String, String>())
+        val callback = object : ScanCallback() {
+            override fun onScanResult(callbackType: Int, result: ScanResult) {
+                val address = result.device.address ?: return
+                val name = result.scanRecord?.deviceName ?: result.device.name ?: ""
+                seen[address] = "$address|$name|${result.rssi}"
+            }
+
+            override fun onScanFailed(errorCode: Int) {
+                Log.w(TAG, "BLE scan failed with error $errorCode")
+            }
+        }
+
+        try {
+            bleHandler.post { scanner.startScan(callback) }
+            Thread.sleep(timeoutMs)
+        } catch (_: InterruptedException) {
+            Thread.currentThread().interrupt()
+        } finally {
+            try { bleHandler.post { scanner.stopScan(callback) } } catch (_: SecurityException) {}
+        }
+        return seen.values.toList()
+    }
+
+    /**
+     * Connect to the BLE peripheral at [address] and locate the GATT
+     * characteristic identified by [writeCharUuid] across all services.
+     *
+     * Blocks until connected + services discovered, or returns -1 on failure.
+     * The returned integer is an opaque handle passed to [write]/[disconnect].
+     */
+    @JvmStatic
+    fun connect(address: String, writeCharUuid: String): Int {
+        val adapter = adapter() ?: return -1
+        val device = try { adapter.getRemoteDevice(address) } catch (e: Exception) {
+            Log.e(TAG, "Invalid BLE address '$address': ${e.message}")
+            return -1
+        }
+
+        val readyDeferred = CompletableDeferred<Boolean>()
+
+        val callback = object : BluetoothGattCallback() {
+            override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
+                when {
+                    newState == BluetoothProfile.STATE_CONNECTED
+                            && status == BluetoothGatt.GATT_SUCCESS -> {
+                        Log.d(TAG, "GATT connected to $address, discovering services")
+                        gatt.discoverServices()
+                    }
+                    newState == BluetoothProfile.STATE_DISCONNECTED -> {
+                        Log.w(TAG, "GATT disconnected from $address (status=$status)")
+                        readyDeferred.complete(false)
+                    }
+                }
+            }
+
+            override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
+                readyDeferred.complete(status == BluetoothGatt.GATT_SUCCESS)
+            }
+
+            override fun onCharacteristicWrite(
+                gatt: BluetoothGatt,
+                characteristic: BluetoothGattCharacteristic,
+                status: Int,
+            ) {
+                val h = handles.entries.firstOrNull { it.value.gatt === gatt }?.key ?: return
+                pendingWrites.remove(h)?.complete(status == BluetoothGatt.GATT_SUCCESS)
+            }
+        }
+
+        val gatt: BluetoothGatt = try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                device.connectGatt(
+                    ctx(), false, callback,
+                    android.bluetooth.BluetoothDevice.TRANSPORT_LE,
+                    android.bluetooth.BluetoothDevice.PHY_LE_1M_MASK,
+                    bleHandler,
+                )
+            } else {
+                @Suppress("DEPRECATION")
+                device.connectGatt(
+                    ctx(), false, callback,
+                    android.bluetooth.BluetoothDevice.TRANSPORT_LE,
+                )
+            }
+        } catch (e: SecurityException) {
+            Log.e(TAG, "BLUETOOTH_CONNECT permission denied for $address", e)
+            return -1
+        } catch (e: Exception) {
+            Log.e(TAG, "connectGatt failed for $address", e)
+            return -1
+        }
+
+        val ready = try {
+            runBlocking { withTimeout(CONNECT_TIMEOUT_MS) { readyDeferred.await() } }
+        } catch (_: TimeoutCancellationException) {
+            Log.e(TAG, "BLE connect+discovery timed out for $address")
+            runCatching { gatt.close() }
+            return -1
+        }
+
+        if (!ready) {
+            runCatching { gatt.close() }
+            return -1
+        }
+
+        val charUuid = try { UUID.fromString(writeCharUuid) } catch (e: Exception) {
+            Log.e(TAG, "Invalid characteristic UUID '$writeCharUuid'")
+            gatt.disconnect(); gatt.close()
+            return -1
+        }
+        val writeChar = gatt.services.flatMap { it.characteristics }
+            .firstOrNull { it.uuid == charUuid }
+
+        if (writeChar == null) {
+            Log.e(TAG, "Characteristic $writeCharUuid not found on $address")
+            gatt.disconnect(); gatt.close()
+            return -1
+        }
+
+        val handle = handleSeq.getAndIncrement()
+        handles[handle] = GattHandle(gatt, writeChar)
+        Log.i(TAG, "BLE connected: address=$address char=$writeCharUuid handle=$handle")
+        return handle
+    }
+
+    /**
+     * Write [data] to the characteristic associated with [handle].
+     *
+     * [withResponse] controls the GATT write type:
+     *  - `true`  → Write Request  (waits for device ACK, slower but reliable)
+     *  - `false` → Write Command  (fire-and-forget, faster, used by SP110E/Triones/Zengge)
+     *
+     * Returns `true` on success, `false` on any error.
+     */
+    @JvmStatic
+    fun write(handle: Int, data: ByteArray, withResponse: Boolean): Boolean {
+        val entry = handles[handle] ?: return false
+        val gatt = entry.gatt
+        val char = entry.writeChar
+        val writeType = if (withResponse)
+            BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
+        else
+            BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
+
+        return if (withResponse) {
+            val deferred = CompletableDeferred<Boolean>()
+            pendingWrites[handle] = deferred
+
+            val initiated = gattWrite(gatt, char, data, writeType)
+            if (!initiated) {
+                pendingWrites.remove(handle)
+                return false
+            }
+            try {
+                runBlocking { withTimeout(WRITE_TIMEOUT_MS) { deferred.await() } }
+            } catch (_: TimeoutCancellationException) {
+                pendingWrites.remove(handle)
+                Log.w(TAG, "BLE write-with-response timed out on handle $handle")
+                false
+            }
+        } else {
+            gattWrite(gatt, char, data, writeType)
+        }
+    }
+
+    /** Disconnect and close the GATT connection for [handle]. */
+    @JvmStatic
+    fun disconnect(handle: Int) {
+        val entry = handles.remove(handle) ?: return
+        pendingWrites.remove(handle)?.complete(false)
+        runCatching {
+            entry.gatt.disconnect()
+            entry.gatt.close()
+        }.onFailure { Log.w(TAG, "BLE disconnect error for handle $handle: ${it.message}") }
+        Log.i(TAG, "BLE disconnected handle=$handle")
+    }
+
+    // ─── Internal helpers ─────────────────────────────────────────────────────
+
+    private fun gattWrite(
+        gatt: BluetoothGatt,
+        char: BluetoothGattCharacteristic,
+        data: ByteArray,
+        writeType: Int,
+    ): Boolean = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+        gatt.writeCharacteristic(char, data, writeType) ==
+                android.bluetooth.BluetoothStatusCodes.SUCCESS
+    } else {
+        @Suppress("DEPRECATION")
+        char.writeType = writeType
+        @Suppress("DEPRECATION")
+        char.value = data
+        @Suppress("DEPRECATION")
+        gatt.writeCharacteristic(char)
+    }
+}

android/app/src/main/java/com/ledgrab/android/BootReceiver.kt

@@ -0,0 +1,62 @@
+package com.ledgrab.android
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import androidx.core.content.ContextCompat
+
+/**
+ * Starts the LedGrab capture service automatically on device boot and
+ * after the app is updated.
+ *
+ * Autostart is best-effort and deliberately limited:
+ *  - Requires root. MediaProjection consent cannot be granted silently,
+ *    so we can't resume capture on unrooted boxes without the user
+ *    walking up to the TV and tapping Start.
+ *  - Gated behind [AutostartPrefs] so the user can opt out.
+ *
+ * Receivers declared with BOOT_COMPLETED must be fast — we hand off to
+ * a foreground service within milliseconds and let the service do the
+ * heavy lifting (Chaquopy bootstrap, pipeline setup).
+ */
+class BootReceiver : BroadcastReceiver() {
+
+    override fun onReceive(context: Context, intent: Intent) {
+        val action = intent.action
+        Log.i(TAG, "Boot event: $action")
+
+        if (action != Intent.ACTION_BOOT_COMPLETED
+            && action != Intent.ACTION_LOCKED_BOOT_COMPLETED
+            && action != Intent.ACTION_MY_PACKAGE_REPLACED
+        ) {
+            return
+        }
+
+        if (!AutostartPrefs(context).isEnabled) {
+            Log.i(TAG, "Autostart disabled — skipping")
+            return
+        }
+
+        // Cheap check first (no process spawn). The real `su -c id` probe
+        // would block and may not complete before the OS reclaims us.
+        if (!Root.looksRooted()) {
+            Log.i(TAG, "Device not rooted — cannot autostart without MediaProjection consent")
+            return
+        }
+
+        try {
+            ContextCompat.startForegroundService(
+                context,
+                CaptureService.createRootIntent(context),
+            )
+            Log.i(TAG, "LedGrab capture service dispatched on boot")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start service on boot", e)
+        }
+    }
+
+    companion object {
+        private const val TAG = "BootReceiver"
+    }
+}

android/app/src/main/java/com/ledgrab/android/CaptureService.kt

@@ -0,0 +1,353 @@
+package com.ledgrab.android
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.media.projection.MediaProjection
+import android.media.projection.MediaProjectionManager
+import android.os.Build
+import android.os.IBinder
+import android.util.DisplayMetrics
+import android.util.Log
+import android.view.WindowManager
+import androidx.core.app.NotificationCompat
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+
+/**
+ * Foreground service that runs the Python LedGrab server and captures
+ * the screen via MediaProjection.
+ */
+class CaptureService : Service() {
+
+    companion object {
+        private const val TAG = "CaptureService"
+        private const val CHANNEL_ID = "ledgrab_capture"
+        private const val NOTIFICATION_ID = 1
+        private const val EXTRA_RESULT_CODE = "result_code"
+        private const val EXTRA_RESULT_DATA = "result_data"
+        private const val EXTRA_USE_ROOT = "use_root"
+        private const val SERVER_PORT = 8080
+        private const val CAPTURE_WIDTH = 480
+        private const val CAPTURE_HEIGHT = 270
+        private const val CAPTURE_FPS = 30
+
+        // Watchdog: if no new root-capture frames arrive inside this
+        // window the pipeline is considered stalled and respawned.
+        // Grace gives screenrecord time to produce its first I-frame.
+        private const val WATCHDOG_GRACE_MS = 5_000L
+        private const val WATCHDOG_CHECK_MS = 5_000L
+        private const val WATCHDOG_MAX_RESTARTS = 3
+
+        /** True while the service is alive.  Survives activity recreation. */
+        @Volatile
+        @JvmStatic
+        var isRunning: Boolean = false
+            private set
+
+        fun createIntent(
+            context: Context,
+            resultCode: Int,
+            resultData: Intent,
+        ): Intent {
+            return Intent(context, CaptureService::class.java).apply {
+                putExtra(EXTRA_RESULT_CODE, resultCode)
+                putExtra(EXTRA_RESULT_DATA, resultData)
+            }
+        }
+
+        /** Root-mode intent — no MediaProjection consent data required. */
+        fun createRootIntent(context: Context): Intent {
+            return Intent(context, CaptureService::class.java).apply {
+                putExtra(EXTRA_USE_ROOT, true)
+            }
+        }
+    }
+
+    private var bridge: PythonBridge? = null
+    private var screenCapture: ScreenCapture? = null
+    private var rootCapture: RootScreenrecord? = null
+    private var mediaProjection: MediaProjection? = null
+
+    // Service-scoped coroutine scope for the root-capture watchdog.
+    // SupervisorJob so a watchdog crash doesn't tear down other children.
+    private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+    private var watchdogJob: Job? = null
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onCreate() {
+        super.onCreate()
+        createNotificationChannel()
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        // CRITICAL: startForeground must be called IMMEDIATELY —
+        // before any other work, especially before getMediaProjection().
+        val localIp = NetworkUtils.getLocalIpAddress(this) ?: "unknown"
+        val url = "http://$localIp:$SERVER_PORT"
+        try {
+            startForeground(NOTIFICATION_ID, buildNotification(url))
+        } catch (e: Exception) {
+            // Most common cause: missing foregroundServiceType permission
+            // or denied POST_NOTIFICATIONS on API 34+.
+            Log.e(TAG, "startForeground failed — service cannot run", e)
+            stopSelf()
+            return START_NOT_STICKY
+        }
+        // Only flip the public flag once the FG transition has succeeded,
+        // otherwise `isRunning=true` sticks forever when startForeground throws.
+        isRunning = true
+
+        val useRoot = intent?.getBooleanExtra(EXTRA_USE_ROOT, false) ?: false
+
+        if (intent == null && !useRoot) {
+            // MediaProjection mode can't recover from a redelivery —
+            // the consent token in the original intent is single-use.
+            Log.w(TAG, "Service restarted without intent (MediaProjection mode) — stopping")
+            isRunning = false
+            stopSelf()
+            return START_NOT_STICKY
+        }
+
+        try {
+            if (useRoot) {
+                startRootCapture(url)
+            } else {
+                startMediaProjectionCapture(intent!!, url)
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start capture", e)
+            isRunning = false
+            stopSelf()
+        }
+
+        // Root mode can be cleanly restarted from the original intent
+        // because it carries no perishable consent token. MediaProjection
+        // mode cannot — a restart there would silently start the service
+        // with a dead projection. START_NOT_STICKY there, the user has
+        // to tap Start again.
+        return if (useRoot) START_REDELIVER_INTENT else START_NOT_STICKY
+    }
+
+    private fun startRootCapture(url: String) {
+        val newBridge = PythonBridge(this).also { b ->
+            b.configureRootCapture(CAPTURE_WIDTH, CAPTURE_HEIGHT)
+            b.startServer(SERVER_PORT)
+        }
+        bridge = newBridge
+
+        val pipeline = RootScreenrecord(
+            bridge = newBridge,
+            width = CAPTURE_WIDTH,
+            height = CAPTURE_HEIGHT,
+            fps = CAPTURE_FPS,
+        )
+        if (!pipeline.start()) {
+            Log.w(TAG, "Root capture failed to launch — stopping service")
+            stopSelf()
+            return
+        }
+        rootCapture = pipeline
+        startWatchdog()
+        Log.i(TAG, "LedGrab service started (root mode) — web UI at $url")
+    }
+
+    /**
+     * Replace the active root pipeline with a fresh instance, reusing
+     * the existing Python bridge (no server restart). Returns true if
+     * the new pipeline launched, false otherwise.
+     */
+    private fun restartRootPipeline(): Boolean {
+        val currentBridge = bridge ?: return false
+        val old = rootCapture
+        rootCapture = null
+        runCatching { old?.stop() }
+
+        val next = RootScreenrecord(
+            bridge = currentBridge,
+            width = CAPTURE_WIDTH,
+            height = CAPTURE_HEIGHT,
+            fps = CAPTURE_FPS,
+        )
+        if (!next.start()) {
+            Log.e(TAG, "Root capture failed to restart")
+            return false
+        }
+        rootCapture = next
+        return true
+    }
+
+    /**
+     * Monitor the root pipeline's frame counter.  If no new frames
+     * arrive within one check window, respawn the pipeline.  Caps at
+     * [WATCHDOG_MAX_RESTARTS] consecutive failures before giving up so
+     * we don't burn battery forever on a device that genuinely can't
+     * produce frames.
+     */
+    private fun startWatchdog() {
+        watchdogJob?.cancel()
+        watchdogJob = serviceScope.launch {
+            delay(WATCHDOG_GRACE_MS)
+            var last = rootCapture?.framesDelivered ?: 0
+            var restartAttempts = 0
+            while (isActive) {
+                delay(WATCHDOG_CHECK_MS)
+                val pipe = rootCapture ?: break
+                val current = pipe.framesDelivered
+                if (current == last) {
+                    restartAttempts += 1
+                    Log.w(
+                        TAG,
+                        "Root capture stalled (no new frames in ${WATCHDOG_CHECK_MS}ms); " +
+                            "restart attempt $restartAttempts/$WATCHDOG_MAX_RESTARTS",
+                    )
+                    if (restartAttempts > WATCHDOG_MAX_RESTARTS) {
+                        Log.e(TAG, "Watchdog gave up after $WATCHDOG_MAX_RESTARTS restarts")
+                        stopSelf()
+                        return@launch
+                    }
+                    if (!restartRootPipeline()) {
+                        stopSelf()
+                        return@launch
+                    }
+                    last = rootCapture?.framesDelivered ?: 0
+                } else {
+                    // Forward progress — forgive earlier glitches.
+                    restartAttempts = 0
+                    last = current
+                }
+            }
+        }
+    }
+
+    private fun startMediaProjectionCapture(intent: Intent, url: String) {
+        val resultCode = intent.getIntExtra(EXTRA_RESULT_CODE, 0)
+        @Suppress("DEPRECATION")
+        val resultData = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            intent.getParcelableExtra(EXTRA_RESULT_DATA, Intent::class.java)
+        } else {
+            intent.getParcelableExtra(EXTRA_RESULT_DATA)
+        }
+
+        if (resultData == null) {
+            Log.e(TAG, "No MediaProjection result data")
+            stopSelf()
+            return
+        }
+
+        val projectionManager =
+            getSystemService(Context.MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
+        val projection = projectionManager.getMediaProjection(resultCode, resultData)
+        if (projection == null) {
+            Log.e(TAG, "Failed to create MediaProjection")
+            stopSelf()
+            return
+        }
+        mediaProjection = projection
+
+        val metrics = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            val windowMetrics = (getSystemService(Context.WINDOW_SERVICE) as WindowManager)
+                .currentWindowMetrics
+            DisplayMetrics().apply {
+                val bounds = windowMetrics.bounds
+                widthPixels = bounds.width()
+                heightPixels = bounds.height()
+                // densityDpi is still needed for VirtualDisplay; read from resources.
+                densityDpi = resources.displayMetrics.densityDpi
+            }
+        } else {
+            val windowManager = getSystemService(Context.WINDOW_SERVICE) as WindowManager
+            DisplayMetrics().also { m ->
+                @Suppress("DEPRECATION")
+                windowManager.defaultDisplay.getRealMetrics(m)
+            }
+        }
+
+        val newBridge = PythonBridge(this).also { b ->
+            b.configureCapture(CAPTURE_WIDTH, CAPTURE_HEIGHT)
+            b.startServer(SERVER_PORT)
+        }
+        bridge = newBridge
+
+        screenCapture = ScreenCapture(
+            projection = projection,
+            metrics = metrics,
+            bridge = newBridge,
+            targetWidth = CAPTURE_WIDTH,
+            targetHeight = CAPTURE_HEIGHT,
+            targetFps = CAPTURE_FPS,
+            // If the user taps the system Cast/Screen-capture stop banner,
+            // MediaProjection.Callback.onStop fires — tear the whole
+            // service down so the notification/Python server don't linger.
+            onProjectionStopped = { stopSelf() },
+        ).also { it.start() }
+
+        Log.i(TAG, "LedGrab service started (MediaProjection) — web UI at $url")
+    }
+
+    override fun onDestroy() {
+        isRunning = false
+
+        watchdogJob?.cancel()
+        watchdogJob = null
+        serviceScope.cancel()
+
+        screenCapture?.stop()
+        screenCapture = null
+
+        rootCapture?.stop()
+        rootCapture = null
+
+        bridge?.stopServer()
+        bridge = null
+
+        mediaProjection?.stop()
+        mediaProjection = null
+
+        Log.i(TAG, "LedGrab service destroyed")
+        super.onDestroy()
+    }
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID,
+                "LedGrab Screen Capture",
+                NotificationManager.IMPORTANCE_LOW,
+            ).apply {
+                description = "Shows while LedGrab is capturing the screen"
+            }
+            val manager = getSystemService(NotificationManager::class.java)
+            manager.createNotificationChannel(channel)
+        }
+    }
+
+    private fun buildNotification(url: String): Notification {
+        val tapIntent = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, MainActivity::class.java).apply {
+                flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
+            },
+            PendingIntent.FLAG_IMMUTABLE,
+        )
+        return NotificationCompat.Builder(this, CHANNEL_ID)
+            .setContentTitle("LedGrab Running")
+            .setContentText("Web UI: $url")
+            .setSmallIcon(R.drawable.ic_launcher)
+            .setContentIntent(tapIntent)
+            .setOngoing(true)
+            .build()
+    }
+}

android/app/src/main/java/com/ledgrab/android/LedGrabApp.kt

@@ -0,0 +1,83 @@
+package com.ledgrab.android
+
+import android.app.Application
+import android.util.Log
+import com.chaquo.python.Python
+import com.chaquo.python.android.AndroidPlatform
+import java.io.File
+import java.io.PrintWriter
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+
+/**
+ * Application class — initializes the Chaquopy Python runtime and
+ * installs a global uncaught exception handler that persists crash
+ * logs to app-private storage.
+ *
+ * `Python.start()` must be called once before any Python code runs.
+ * It loads libpython, extracts stdlib + pip packages from APK assets
+ * (first launch only), and sets up `sys.path`.
+ */
+class LedGrabApp : Application() {
+
+    /** Set if [Python.start] threw — surfaced by MainActivity. */
+    @Volatile
+    var initError: Throwable? = null
+        private set
+
+    override fun onCreate() {
+        super.onCreate()
+        installCrashLogger()
+        try {
+            if (!Python.isStarted()) {
+                Python.start(AndroidPlatform(this))
+            }
+        } catch (t: Throwable) {
+            // Don't crash here — MainActivity will render a failure
+            // screen with a Copy log button so the user can report it.
+            Log.e(TAG, "Python.start() failed", t)
+            initError = t
+            return
+        }
+        // Bind application context for the USB-serial bridge so Python
+        // can enumerate and open USB-to-TTL adapters without needing
+        // an Activity reference.
+        UsbSerialBridge.init(this)
+        // Bind application context for the BLE bridge so Python can
+        // scan and connect to BLE LED controllers.
+        BleBridge.init(this)
+    }
+
+    /**
+     * Install a global uncaught exception handler that writes the
+     * stack trace to `files/crash-<timestamp>.log` before letting
+     * the default handler terminate the process.  Logs survive app
+     * restarts and can be pulled via `adb pull` for diagnostics.
+     */
+    private fun installCrashLogger() {
+        val defaultHandler = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            try {
+                val ts = SimpleDateFormat("yyyyMMdd-HHmmss", Locale.US).format(Date())
+                val logFile = File(filesDir, "crash-$ts.log")
+                PrintWriter(logFile).use { pw ->
+                    pw.println("LedGrab crash at $ts")
+                    pw.println("Thread: ${thread.name}")
+                    pw.println()
+                    throwable.printStackTrace(pw)
+                }
+                Log.e(TAG, "Crash log written to ${logFile.absolutePath}")
+            } catch (_: Exception) {
+                // Best effort — don't crash inside the crash handler.
+            }
+            // Chain to the default handler so Android shows the crash dialog
+            // and terminates the process.
+            defaultHandler?.uncaughtException(thread, throwable)
+        }
+    }
+
+    companion object {
+        private const val TAG = "LedGrabApp"
+    }
+}

android/app/src/main/java/com/ledgrab/android/MainActivity.kt

@@ -0,0 +1,314 @@
+package com.ledgrab.android
+
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.graphics.Bitmap
+import android.media.projection.MediaProjectionManager
+import android.net.Uri
+import android.os.Build
+import android.os.Bundle
+import android.os.PowerManager
+import android.provider.Settings
+import android.util.Log
+import android.view.View
+import android.widget.Button
+import android.widget.CheckBox
+import android.widget.ImageView
+import android.widget.TextView
+import android.app.Activity
+import androidx.core.content.ContextCompat
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.qrcode.QRCodeWriter
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.MainScope
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+/**
+ * Main (and only) Activity for the Android TV app.
+ *
+ * Two-state UI: stopped (Start button) and running (URL + QR + Stop).
+ * Navigable with D-pad / USB controller.
+ */
+class MainActivity : Activity() {
+
+    // Activity-scoped coroutine scope. We don't depend on AppCompat /
+    // androidx.lifecycle's lifecycleScope here because the TV launcher
+    // theme inherits from Leanback (non-AppCompat).
+    private val uiScope: CoroutineScope = MainScope()
+
+    companion object {
+        private const val TAG = "MainActivity"
+        private const val SERVER_PORT = 8080
+        private const val REQUEST_MEDIA_PROJECTION = 1001
+        private const val REQUEST_POST_NOTIFICATIONS = 1002
+    }
+
+    private lateinit var stoppedPanel: View
+    private lateinit var runningPanel: View
+    private lateinit var statusText: TextView
+    private lateinit var urlText: TextView
+    private lateinit var qrImage: ImageView
+    private lateinit var toggleButton: Button
+    private lateinit var stopButtonRunning: Button
+    private lateinit var versionText: TextView
+    private lateinit var autostartCheck: CheckBox
+    private lateinit var autostartPrefs: AutostartPrefs
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // Surface fatal Python init errors instead of crashing.
+        val initError = (application as? LedGrabApp)?.initError
+        if (initError != null) {
+            showFatalErrorScreen(initError)
+            return
+        }
+
+        setContentView(R.layout.activity_main)
+
+        stoppedPanel = findViewById(R.id.stopped_panel)
+        runningPanel = findViewById(R.id.running_panel)
+        statusText = findViewById(R.id.status_text)
+        urlText = findViewById(R.id.url_text)
+        qrImage = findViewById(R.id.qr_image)
+        toggleButton = findViewById(R.id.toggle_button)
+        stopButtonRunning = findViewById(R.id.stop_button_running)
+        versionText = findViewById(R.id.version_text)
+        autostartCheck = findViewById(R.id.autostart_check)
+
+        val versionName = packageManager
+            .getPackageInfo(packageName, 0).versionName
+        versionText.text = getString(R.string.version_prefix, versionName ?: "?")
+
+        autostartPrefs = AutostartPrefs(this)
+        autostartCheck.isChecked = autostartPrefs.isEnabled
+        // Autostart only takes effect on rooted devices — grey it out
+        // on unrooted hardware so users don't expect magic. Cheap probe
+        // (file-existence only, no process spawn).
+        if (!Root.looksRooted()) {
+            autostartCheck.isEnabled = false
+            autostartCheck.text = getString(R.string.autostart_unavailable)
+        }
+        autostartCheck.setOnCheckedChangeListener { _, isChecked ->
+            autostartPrefs.isEnabled = isChecked
+            if (isChecked) ensureIgnoringBatteryOptimizations()
+        }
+
+        toggleButton.setOnClickListener { startCapture() }
+        stopButtonRunning.setOnClickListener { stopCaptureService() }
+
+        updateUI()
+    }
+
+    /**
+     * Decide whether to go through the MediaProjection consent flow or
+     * jump straight into root capture. Root check is fast but may block
+     * briefly the first time Magisk shows its grant dialog — running it
+     * on the UI thread is acceptable because we're responding to a
+     * button press and we want to block until the user answers.
+     */
+    override fun onDestroy() {
+        uiScope.cancel()
+        super.onDestroy()
+    }
+
+    private fun startCapture() {
+        // `su -c id` can block for seconds while Magisk shows its grant
+        // dialog; running it on the Main thread caused ANRs.
+        toggleButton.isEnabled = false
+        statusText.text = "Checking root access…"
+        uiScope.launch(Dispatchers.IO) {
+            val rooted = Root.requestGrant()
+            withContext(Dispatchers.Main) {
+                toggleButton.isEnabled = true
+                statusText.text = ""
+                if (rooted) {
+                    Log.i(TAG, "Root available — skipping MediaProjection consent")
+                    startRootCaptureService()
+                } else {
+                    requestMediaProjection()
+                }
+            }
+        }
+    }
+
+    private fun requestMediaProjection() {
+        val manager = getSystemService(MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
+        @Suppress("DEPRECATION")
+        startActivityForResult(manager.createScreenCaptureIntent(), REQUEST_MEDIA_PROJECTION)
+    }
+
+    private fun startRootCaptureService() {
+        ensureNotificationPermission()
+        ContextCompat.startForegroundService(this, CaptureService.createRootIntent(this))
+        updateUI()
+    }
+
+    @Deprecated("Using deprecated API for plain Activity compatibility")
+    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
+        super.onActivityResult(requestCode, resultCode, data)
+        if (requestCode == REQUEST_MEDIA_PROJECTION) {
+            if (resultCode == RESULT_OK && data != null) {
+                startCaptureService(resultCode, data)
+            } else {
+                statusText.text = "Permission denied — screen capture requires authorization"
+                Log.w(TAG, "MediaProjection permission denied")
+            }
+        }
+    }
+
+    private fun startCaptureService(resultCode: Int, resultData: Intent) {
+        ensureNotificationPermission()
+        val intent = CaptureService.createIntent(this, resultCode, resultData)
+        ContextCompat.startForegroundService(this, intent)
+        updateUI()
+    }
+
+    private fun stopCaptureService() {
+        stopService(Intent(this, CaptureService::class.java))
+        updateUI()
+    }
+
+    private fun updateUI() {
+        if (CaptureService.isRunning) {
+            val localIp = NetworkUtils.getLocalIpAddress(this) ?: "unknown"
+            val url = "http://$localIp:$SERVER_PORT"
+
+            urlText.text = url
+            qrImage.setImageBitmap(null)
+            // Build the bitmap pixels off the Main thread — encode + 313k
+            // setPixel calls were noticeably janky on slow TV boxes.
+            uiScope.launch(Dispatchers.Default) {
+                val bitmap = generateQrCode(url)
+                withContext(Dispatchers.Main) {
+                    if (CaptureService.isRunning && urlText.text == url) {
+                        qrImage.setImageBitmap(bitmap)
+                    }
+                }
+            }
+
+            stoppedPanel.visibility = View.GONE
+            versionText.visibility = View.GONE
+            runningPanel.visibility = View.VISIBLE
+            stopButtonRunning.requestFocus()
+        } else {
+            urlText.text = ""
+            qrImage.setImageBitmap(null)
+
+            runningPanel.visibility = View.GONE
+            stoppedPanel.visibility = View.VISIBLE
+            versionText.visibility = View.VISIBLE
+            toggleButton.requestFocus()
+        }
+    }
+
+    private fun generateQrCode(text: String): Bitmap {
+        val size = 560
+        val bitMatrix = QRCodeWriter().encode(text, BarcodeFormat.QR_CODE, size, size)
+        val pixels = IntArray(size * size)
+        for (y in 0 until size) {
+            val rowOffset = y * size
+            for (x in 0 until size) {
+                pixels[rowOffset + x] =
+                    if (bitMatrix[x, y]) 0xFF000000.toInt() else 0xFFFFFFFF.toInt()
+            }
+        }
+        val bitmap = Bitmap.createBitmap(size, size, Bitmap.Config.RGB_565)
+        bitmap.setPixels(pixels, 0, size, 0, 0, size, size)
+        return bitmap
+    }
+
+    /**
+     * Minimal failure UI shown when Python.start() (Chaquopy) blew up.
+     * Rendered programmatically so we don't depend on the regular layout
+     * (which itself may reference resources affected by the failure).
+     */
+    private fun showFatalErrorScreen(error: Throwable) {
+        Log.e(TAG, "Fatal init error — showing error screen", error)
+        val stackText = android.util.Log.getStackTraceString(error)
+        val container = android.widget.LinearLayout(this).apply {
+            orientation = android.widget.LinearLayout.VERTICAL
+            setPadding(48, 48, 48, 48)
+        }
+        val title = TextView(this).apply {
+            text = "LedGrab failed to start"
+            textSize = 22f
+        }
+        val body = TextView(this).apply {
+            text = "Python runtime initialization failed:\n\n$stackText"
+            textSize = 12f
+            setTextIsSelectable(true)
+        }
+        val copyBtn = Button(this).apply {
+            text = "Copy log"
+            setOnClickListener {
+                val cm = getSystemService(CLIPBOARD_SERVICE)
+                    as android.content.ClipboardManager
+                cm.setPrimaryClip(
+                    android.content.ClipData.newPlainText("LedGrab error", stackText)
+                )
+            }
+        }
+        val scroll = android.widget.ScrollView(this).apply { addView(body) }
+        container.addView(title)
+        container.addView(copyBtn)
+        container.addView(scroll)
+        setContentView(container)
+    }
+
+    /**
+     * Prompt the user to exempt LedGrab from battery optimization.  On
+     * TV boxes this is usually a no-op, but on phones Doze/App Standby
+     * will kill the foreground service after a few hours of sleep.  We
+     * only ask when autostart is turned on.  No-op on pre-M or when
+     * already exempt.
+     *
+     * Play Store flags REQUEST_IGNORE_BATTERY_OPTIMIZATIONS by default
+     * — LedGrab's ambient-capture use case falls under the documented
+     * acceptable-use exceptions (a foreground service that must not be
+     * killed to fulfill its primary function).
+     */
+    @SuppressLint("BatteryLife")
+    private fun ensureIgnoringBatteryOptimizations() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) return
+        val pm = getSystemService(POWER_SERVICE) as PowerManager
+        if (pm.isIgnoringBatteryOptimizations(packageName)) return
+        try {
+            val intent = Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS).apply {
+                data = Uri.parse("package:$packageName")
+            }
+            startActivity(intent)
+        } catch (e: Exception) {
+            // Some TV-box OEM builds strip this intent. Fall back to the
+            // generic settings screen so the user can find it manually.
+            Log.w(TAG, "Direct exemption intent unavailable: ${e.message}")
+            runCatching {
+                startActivity(Intent(Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS))
+            }
+        }
+    }
+
+    /**
+     * Request POST_NOTIFICATIONS permission on Android 13+ so the
+     * foreground service notification is visible.  On older API levels
+     * this is a no-op.
+     */
+    private fun ensureNotificationPermission() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            if (checkSelfPermission(Manifest.permission.POST_NOTIFICATIONS)
+                != PackageManager.PERMISSION_GRANTED
+            ) {
+                @Suppress("DEPRECATION")
+                requestPermissions(
+                    arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+                    REQUEST_POST_NOTIFICATIONS,
+                )
+            }
+        }
+    }
+}

android/app/src/main/java/com/ledgrab/android/NetworkUtils.kt

@@ -0,0 +1,28 @@
+package com.ledgrab.android
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.LinkProperties
+import java.net.Inet4Address
+
+/**
+ * Network utilities for discovering the device's local IP address.
+ */
+object NetworkUtils {
+
+    /**
+     * Return the device's local IPv4 address on the active network,
+     * or `null` if unavailable.
+     */
+    fun getLocalIpAddress(context: Context): String? {
+        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+        val network = cm.activeNetwork ?: return null
+        val props: LinkProperties = cm.getLinkProperties(network) ?: return null
+
+        return props.linkAddresses
+            .map { it.address }
+            .filterIsInstance<Inet4Address>()
+            .firstOrNull { !it.isLoopbackAddress }
+            ?.hostAddress
+    }
+}

android/app/src/main/java/com/ledgrab/android/PythonBridge.kt

@@ -0,0 +1,141 @@
+package com.ledgrab.android
+
+import android.content.Context
+import android.util.Log
+import com.chaquo.python.PyObject
+import com.chaquo.python.Python
+
+/**
+ * Bridge between Kotlin and the LedGrab Python server.
+ *
+ * All Python calls go through Chaquopy's `Python.getInstance()`.
+ * Frame data crosses the JNI boundary as a `ByteArray`.
+ */
+class PythonBridge(private val context: Context) {
+
+    companion object {
+        private const val TAG = "PythonBridge"
+    }
+
+    private var serverThread: Thread? = null
+    @Volatile private var running = false
+
+    // Cached PyObject handles for the per-frame fast path. Looking these
+    // up via Python.getInstance().getModule(...) every frame was a real
+    // measurable cost (~1ms/frame on TV boxes). Cached once at configure
+    // time and read on the capture thread — @Volatile is enough for the
+    // single-writer/single-reader pattern we have here.
+    @Volatile private var mediaProjectionEngine: PyObject? = null
+    @Volatile private var rootEngine: PyObject? = null
+
+    /**
+     * Configure the MediaProjection engine with screen dimensions.
+     * Must be called before [startServer].
+     */
+    fun configureCapture(width: Int, height: Int) {
+        val py = Python.getInstance()
+        val engine = py.getModule("ledgrab.core.capture_engines.mediaprojection_engine")
+        engine.callAttr("configure", width, height)
+        mediaProjectionEngine = engine
+        Log.i(TAG, "MediaProjection engine configured: ${width}x${height}")
+    }
+
+    /**
+     * Configure the root screenrecord engine with screen dimensions.
+     * Used instead of [configureCapture] when root is available.
+     */
+    fun configureRootCapture(width: Int, height: Int) {
+        val py = Python.getInstance()
+        val engine = py.getModule("ledgrab.core.capture_engines.root_screenrecord_engine")
+        engine.callAttr("configure", width, height)
+        rootEngine = engine
+        Log.i(TAG, "Root screenrecord engine configured: ${width}x${height}")
+    }
+
+    /**
+     * Start the LedGrab FastAPI server on a background thread.
+     *
+     * This blocks until [stopServer] is called, so it runs in its own thread.
+     */
+    fun startServer(port: Int = 8080) {
+        if (running) {
+            Log.w(TAG, "Server already running")
+            return
+        }
+
+        running = true
+        val dataDir = context.filesDir.absolutePath
+
+        serverThread = Thread({
+            try {
+                Log.i(TAG, "Starting Python server (dataDir=$dataDir, port=$port)")
+                val py = Python.getInstance()
+                val entry = py.getModule("ledgrab.android_entry")
+                entry.callAttr("start_server", dataDir, port)
+            } catch (e: Exception) {
+                Log.e(TAG, "Python server error", e)
+            } finally {
+                running = false
+            }
+        }, "ledgrab-python-server")
+        serverThread?.start()
+    }
+
+    /**
+     * Signal the Python server to shut down gracefully.
+     */
+    fun stopServer() {
+        if (!running) return
+
+        try {
+            val py = Python.getInstance()
+            val entry = py.getModule("ledgrab.android_entry")
+            entry.callAttr("stop_server")
+        } catch (e: Exception) {
+            Log.e(TAG, "Error stopping server", e)
+        }
+
+        serverThread?.join(10_000)
+        serverThread = null
+        running = false
+        Log.i(TAG, "Server stopped")
+    }
+
+    /**
+     * Push a captured RGBA frame to the Python MediaProjection engine.
+     *
+     * Called from [ScreenCapture] on the capture thread.  The byte array
+     * crosses the JNI boundary — keep frames small (downscale to 480p
+     * before calling).
+     */
+    fun pushFrame(rgbaBytes: ByteArray, width: Int, height: Int) {
+        if (!running) return
+        val engine = mediaProjectionEngine ?: return
+
+        try {
+            engine.callAttr("push_frame", rgbaBytes, width, height)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to push frame: ${e.message}")
+        }
+    }
+
+    /**
+     * Push a frame produced by the root `screenrecord` pipeline.
+     *
+     * Routed to a separate Python module so the two capture paths stay
+     * independently introspectable (engine priority, availability flags,
+     * dashboard diagnostics).
+     */
+    fun pushRootFrame(rgbaBytes: ByteArray, width: Int, height: Int) {
+        if (!running) return
+        val engine = rootEngine ?: return
+
+        try {
+            engine.callAttr("push_frame", rgbaBytes, width, height)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to push root frame: ${e.message}")
+        }
+    }
+
+    val isRunning: Boolean get() = running
+}

android/app/src/main/java/com/ledgrab/android/Root.kt

@@ -0,0 +1,136 @@
+package com.ledgrab.android
+
+import android.util.Log
+import java.io.BufferedReader
+import java.io.InputStreamReader
+import java.util.concurrent.TimeUnit
+
+/**
+ * Lightweight root-access utilities.
+ *
+ * Detection is two-phase:
+ *   1. Cheap check for a `su` binary in common paths (no process spawn).
+ *   2. On demand, a real `su -c id` execution that returns true only when
+ *      the shell actually runs as UID 0. This triggers Magisk's grant
+ *      dialog the first time, exactly like any other root request.
+ *
+ * The heavier check is cached after it succeeds so we don't ask Magisk
+ * repeatedly mid-session.
+ */
+object Root {
+    private const val TAG = "Root"
+
+    private val SU_PATHS = listOf(
+        "/system/bin/su",
+        "/system/xbin/su",
+        "/sbin/su",
+        "/su/bin/su",
+        "/debug_ramdisk/su",
+        "/vendor/bin/su",
+    )
+
+    @Volatile private var cachedGranted: Boolean? = null
+
+    /** Cheap probe: true if a known `su` binary exists. Doesn't run anything. */
+    @JvmStatic
+    fun looksRooted(): Boolean = SU_PATHS.any { java.io.File(it).exists() }
+
+    /**
+     * Actually exercise `su`. Triggers Magisk's grant dialog on first call.
+     * Returns true if the shell reports UID 0 within the timeout; false
+     * otherwise (no root, user denied, or timeout).
+     */
+    @JvmStatic
+    fun requestGrant(timeoutSeconds: Long = 10): Boolean {
+        cachedGranted?.let { return it }
+
+        if (!looksRooted()) {
+            cachedGranted = false
+            return false
+        }
+
+        val granted = try {
+            // redirectErrorStream merges stderr into stdout so a single
+            // drain thread is enough — avoids the classic pipe-buffer
+            // deadlock where waitFor() blocks because stderr filled up.
+            val process = ProcessBuilder("su", "-c", "id")
+                .redirectErrorStream(true)
+                .start()
+            val outputBuilder = StringBuilder()
+            val drain = Thread({
+                try {
+                    BufferedReader(InputStreamReader(process.inputStream)).use { r ->
+                        val buf = CharArray(512)
+                        while (true) {
+                            val n = r.read(buf)
+                            if (n < 0) break
+                            synchronized(outputBuilder) { outputBuilder.append(buf, 0, n) }
+                        }
+                    }
+                } catch (_: Exception) {
+                    // Process gone — drain ends.
+                }
+            }, "Root-su-drain").apply { isDaemon = true; start() }
+
+            val finished = process.waitFor(timeoutSeconds, TimeUnit.SECONDS)
+            if (!finished) {
+                process.destroyForcibly()
+                drain.join(500)
+                Log.w(TAG, "su -c id timed out after ${timeoutSeconds}s")
+                false
+            } else {
+                drain.join(500)
+                val output = synchronized(outputBuilder) { outputBuilder.toString() }
+                if (process.exitValue() != 0) {
+                    Log.w(TAG, "su -c id exited with ${process.exitValue()} output='${output.trim()}'")
+                    false
+                } else {
+                    val rooted = output.contains("uid=0")
+                    Log.i(TAG, "su -c id → '${output.trim()}' → rooted=$rooted")
+                    rooted
+                }
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "su invocation failed: ${e.message}")
+            false
+        }
+
+        cachedGranted = granted
+        return granted
+    }
+
+    /**
+     * Run an `su -c <cmd>` command. Returns true on exit-zero. Failure
+     * invalidates the cached grant so the next [requestGrant] re-checks
+     * (covers cases like Magisk grant being revoked mid-session).
+     */
+    @JvmStatic
+    fun runAsRoot(cmd: String, timeoutSeconds: Long = 5): Boolean {
+        return try {
+            val process = ProcessBuilder("su", "-c", cmd)
+                .redirectErrorStream(true)
+                .start()
+            val finished = process.waitFor(timeoutSeconds, TimeUnit.SECONDS)
+            if (!finished) {
+                process.destroyForcibly()
+                cachedGranted = null
+                false
+            } else if (process.exitValue() != 0) {
+                cachedGranted = null
+                false
+            } else {
+                true
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "runAsRoot('$cmd') failed: ${e.message}")
+            cachedGranted = null
+            false
+        }
+    }
+
+    /** Forget the cached grant result — useful if Magisk permission was revoked. */
+    @JvmStatic
+    fun invalidateCache() {
+        cachedGranted = null
+    }
+}

android/app/src/main/java/com/ledgrab/android/RootScreenrecord.kt

@@ -0,0 +1,273 @@
+package com.ledgrab.android
+
+import android.graphics.PixelFormat
+import android.media.ImageReader
+import android.media.MediaCodec
+import android.media.MediaFormat
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import java.io.InputStream
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Root-only screen capture backed by `/system/bin/screenrecord`.
+ *
+ * When the device is rooted (Magisk), we spawn ``su -c screenrecord
+ * --output-format=h264 …`` and read the encoder's H.264 bitstream from
+ * stdout. A MediaCodec decoder is configured to render into an
+ * ImageReader's Surface, and the ImageReader's `onImageAvailable`
+ * callback feeds RGBA bytes back to the Python pipeline — same sink as
+ * the MediaProjection path, just a different source.
+ *
+ * Why bother: MediaProjection forces Android to draw a persistent
+ * capture indicator overlay (unavoidable on stock Android 14+). The
+ * root path sidesteps that entirely because `screenrecord` runs as
+ * system UID through `su`. It also skips the one-time MediaProjection
+ * consent dialog, which matters on TV-only setups where keyboard input
+ * is awkward.
+ */
+class RootScreenrecord(
+    private val bridge: PythonBridge,
+    private val width: Int = 480,
+    private val height: Int = 270,
+    private val bitRate: Int = 4_000_000,
+    private val fps: Int = 30,
+) {
+    companion object {
+        private const val TAG = "RootScreenrecord"
+        private const val MIME_TYPE = MediaFormat.MIMETYPE_VIDEO_AVC
+        private const val INPUT_CHUNK = 64 * 1024
+    }
+
+    @Volatile private var process: Process? = null
+    private var decoder: MediaCodec? = null
+    private var imageReader: ImageReader? = null
+    private var readerThread: HandlerThread? = null
+    private var inputThread: Thread? = null
+    private var outputThread: Thread? = null
+    @Volatile private var running = false
+    private val framesDeliveredCounter = AtomicInteger(0)
+    @Volatile private var stopped = false
+
+    /** Monotonic count of frames pushed to the Python bridge. */
+    val framesDelivered: Int get() = framesDeliveredCounter.get()
+
+    /** True once at least one frame has reached the Python bridge. */
+    val hasProducedFrame: Boolean get() = framesDelivered > 0
+
+    /**
+     * Start the capture pipeline. Returns false if `su`/`screenrecord`
+     * couldn't be launched at all; true doesn't guarantee frames will
+     * actually flow (the caller should monitor [hasProducedFrame] and
+     * be ready to fall back to MediaProjection on timeout).
+     */
+    fun start(): Boolean {
+        if (running) return true
+        running = true
+
+        try {
+            imageReader = buildImageReader()
+            decoder = buildDecoder(imageReader!!)
+            process = spawnScreenrecord() ?: run {
+                stop()
+                return false
+            }
+            startInputPump(process!!.inputStream, decoder!!)
+            startOutputDrain(decoder!!)
+            Log.i(TAG, "Root capture pipeline started (${width}x$height @ ${fps}fps)")
+            return true
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start root capture", e)
+            stop()
+            return false
+        }
+    }
+
+    /** Stop everything and release resources. Idempotent. */
+    @Synchronized
+    fun stop() {
+        if (stopped) return
+        stopped = true
+        // Order matters: signal first so worker loops drop out, then
+        // stop the codec on the thread that created it (this one), then
+        // join workers BEFORE releasing the codec/ImageReader they may
+        // still be touching, then kill the external screenrecord process.
+        running = false
+
+        runCatching { decoder?.stop() }
+
+        inputThread?.interrupt()
+        outputThread?.interrupt()
+        runCatching { inputThread?.join(500) }
+        runCatching { outputThread?.join(500) }
+        inputThread = null
+        outputThread = null
+
+        // Best-effort: kill the screenrecord child before reaping `su`,
+        // otherwise screenrecord can outlive su as an orphan and keep
+        // the GPU encoder busy. Fire-and-forget; ignore failures.
+        runCatching { Root.runAsRoot("pkill -TERM screenrecord", timeoutSeconds = 2) }
+
+        runCatching { decoder?.release() }
+        decoder = null
+
+        runCatching { imageReader?.setOnImageAvailableListener(null, null) }
+        runCatching { imageReader?.close() }
+        imageReader = null
+
+        readerThread?.quitSafely()
+        runCatching { readerThread?.join(500) }
+        readerThread = null
+
+        runCatching { process?.destroy() }
+        process = null
+
+        Log.i(TAG, "Root capture pipeline stopped (frames delivered: ${framesDelivered})")
+    }
+
+    private fun buildImageReader(): ImageReader {
+        val thread = HandlerThread("RootReader").apply { start() }
+        readerThread = thread
+        val handler = Handler(thread.looper)
+
+        val reader = ImageReader.newInstance(width, height, PixelFormat.RGBA_8888, 2)
+        reader.setOnImageAvailableListener({ r ->
+            val image = r.acquireLatestImage() ?: return@setOnImageAvailableListener
+            try {
+                val plane = image.planes[0]
+                val buffer = plane.buffer
+                val rowStride = plane.rowStride
+                val pixelStride = plane.pixelStride
+                val bytes = if (rowStride == width * pixelStride) {
+                    ByteArray(buffer.remaining()).also { buffer.get(it) }
+                } else {
+                    // Strip row padding — common when width isn't a multiple of 16.
+                    val rowBytes = width * pixelStride
+                    ByteArray(width * height * 4).also { out ->
+                        for (row in 0 until height) {
+                            buffer.position(row * rowStride)
+                            buffer.get(out, row * rowBytes, rowBytes)
+                        }
+                    }
+                }
+                bridge.pushRootFrame(bytes, width, height)
+                framesDeliveredCounter.incrementAndGet()
+            } catch (e: Exception) {
+                Log.w(TAG, "Root frame delivery failed: ${e.message}")
+            } finally {
+                image.close()
+            }
+        }, handler)
+        return reader
+    }
+
+    private fun buildDecoder(reader: ImageReader): MediaCodec {
+        val format = MediaFormat.createVideoFormat(MIME_TYPE, width, height).apply {
+            setInteger(MediaFormat.KEY_FRAME_RATE, fps)
+        }
+        val codec = MediaCodec.createDecoderByType(MIME_TYPE)
+        codec.configure(format, reader.surface, null, 0)
+        codec.start()
+        return codec
+    }
+
+    private fun spawnScreenrecord(): Process? {
+        val cmd = buildString {
+            append("screenrecord")
+            append(" --output-format=h264")
+            append(" --size=${width}x$height")
+            append(" --bit-rate=$bitRate")
+            // Time limit 0 isn't supported; the largest accepted is 180s.
+            // We restart the process ourselves if it exits early.
+            append(" --time-limit=180")
+            append(" -")
+        }
+        return try {
+            Runtime.getRuntime().exec(arrayOf("su", "-c", cmd))
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to spawn `su -c screenrecord`: ${e.message}")
+            null
+        }
+    }
+
+    private fun startInputPump(initialStream: InputStream, codec: MediaCodec) {
+        inputThread = Thread({
+            val buf = ByteArray(INPUT_CHUNK)
+            var stream: InputStream = initialStream
+            try {
+                outer@ while (running) {
+                    val n = try {
+                        stream.read(buf)
+                    } catch (e: Exception) {
+                        if (!running) break
+                        Log.w(TAG, "screenrecord read error: ${e.message}")
+                        -1
+                    }
+                    if (n <= 0) {
+                        if (!running) break
+                        // screenrecord caps at --time-limit=180s. When it
+                        // exits cleanly we respawn so capture survives
+                        // long sessions instead of freezing after ~3min.
+                        Log.i(TAG, "screenrecord EOF — respawning")
+                        runCatching { process?.destroy() }
+                        val next = spawnScreenrecord()
+                        if (next == null) {
+                            // Avoid a tight loop if `su` is suddenly unhappy.
+                            try { Thread.sleep(500) } catch (_: InterruptedException) { break }
+                            continue@outer
+                        }
+                        process = next
+                        stream = next.inputStream
+                        continue@outer
+                    }
+                    var offset = 0
+                    while (offset < n && running) {
+                        val index = codec.dequeueInputBuffer(50_000)
+                        if (index < 0) continue
+                        val inputBuffer = codec.getInputBuffer(index) ?: continue
+                        inputBuffer.clear()
+                        val chunk = minOf(n - offset, inputBuffer.capacity())
+                        inputBuffer.put(buf, offset, chunk)
+                        codec.queueInputBuffer(
+                            index,
+                            0,
+                            chunk,
+                            System.nanoTime() / 1_000,
+                            0,
+                        )
+                        offset += chunk
+                    }
+                }
+            } catch (_: InterruptedException) {
+                // Expected on stop()
+            } catch (e: Exception) {
+                Log.w(TAG, "Input pump error: ${e.message}")
+            }
+        }, "RootDecoderInput").also { it.start() }
+    }
+
+    private fun startOutputDrain(codec: MediaCodec) {
+        outputThread = Thread({
+            val info = MediaCodec.BufferInfo()
+            try {
+                while (running) {
+                    val index = codec.dequeueOutputBuffer(info, 50_000)
+                    if (index >= 0) {
+                        // `true` = render to the configured surface (ImageReader),
+                        // which triggers onImageAvailable on the reader's handler.
+                        codec.releaseOutputBuffer(index, true)
+                        if (info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0) {
+                            Log.i(TAG, "Decoder reported EOS")
+                            break
+                        }
+                    }
+                }
+            } catch (_: InterruptedException) {
+                // Expected on stop()
+            } catch (e: Exception) {
+                Log.w(TAG, "Output drain error: ${e.message}")
+            }
+        }, "RootDecoderOutput").also { it.start() }
+    }
+}

android/app/src/main/java/com/ledgrab/android/ScreenCapture.kt

@@ -0,0 +1,155 @@
+package com.ledgrab.android
+
+import android.graphics.Bitmap
+import android.graphics.PixelFormat
+import android.hardware.display.DisplayManager
+import android.hardware.display.VirtualDisplay
+import android.media.ImageReader
+import android.media.projection.MediaProjection
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.DisplayMetrics
+import android.util.Log
+import java.nio.ByteBuffer
+
+/**
+ * Captures the Android screen via MediaProjection and feeds frames
+ * to [PythonBridge].
+ *
+ * Frames are downscaled to [targetWidth] x [targetHeight] before
+ * crossing the JNI boundary to minimize overhead.  For LED ambient
+ * lighting, even 480x270 contains far more data than needed.
+ */
+class ScreenCapture(
+    private val projection: MediaProjection,
+    private val metrics: DisplayMetrics,
+    private val bridge: PythonBridge,
+    private val targetWidth: Int = 480,
+    private val targetHeight: Int = 270,
+    private val targetFps: Int = 30,
+    private val onProjectionStopped: () -> Unit = {},
+) {
+    companion object {
+        private const val TAG = "ScreenCapture"
+        private const val VIRTUAL_DISPLAY_NAME = "LedGrabCapture"
+    }
+
+    private var virtualDisplay: VirtualDisplay? = null
+    private var imageReader: ImageReader? = null
+    private var captureThread: HandlerThread? = null
+    private var captureHandler: Handler? = null
+    @Volatile private var running = false
+    private var lastFrameTimeMs = 0L
+    private val frameIntervalMs = 1000L / targetFps
+
+    /**
+     * Start capturing the screen.
+     */
+    fun start() {
+        if (running) return
+        running = true
+
+        captureThread = HandlerThread("LedGrab-Capture").also { it.start() }
+        captureHandler = Handler(captureThread!!.looper)
+
+        // Android 14+ requires registering a callback before createVirtualDisplay
+        projection.registerCallback(object : MediaProjection.Callback() {
+            override fun onStop() {
+                Log.i(TAG, "MediaProjection stopped (external)")
+                stop()
+                // Notify the service so the foreground notification /
+                // Python server get torn down too — otherwise a stale
+                // "Running" notification lingers after the user taps
+                // Android's system Cast/Screen-capture stop banner.
+                onProjectionStopped()
+            }
+        }, captureHandler)
+
+        imageReader = ImageReader.newInstance(
+            targetWidth,
+            targetHeight,
+            PixelFormat.RGBA_8888,
+            2,  // maxImages — double buffer
+        )
+
+        imageReader?.setOnImageAvailableListener({ reader ->
+            if (!running) return@setOnImageAvailableListener
+
+            val now = System.currentTimeMillis()
+            if (now - lastFrameTimeMs < frameIntervalMs) {
+                // Skip frame to maintain target FPS
+                reader.acquireLatestImage()?.close()
+                return@setOnImageAvailableListener
+            }
+
+            val image = reader.acquireLatestImage() ?: return@setOnImageAvailableListener
+            try {
+                val plane = image.planes[0]
+                val buffer = plane.buffer
+                val rowStride = plane.rowStride
+                val pixelStride = plane.pixelStride
+
+                // Handle row padding: rowStride may be > width * pixelStride
+                val rgbaBytes = if (rowStride == targetWidth * pixelStride) {
+                    // No padding — direct copy
+                    val bytes = ByteArray(buffer.remaining())
+                    buffer.get(bytes)
+                    bytes
+                } else {
+                    // Strip row padding
+                    val rowBytes = targetWidth * pixelStride
+                    val bytes = ByteArray(targetWidth * targetHeight * 4)
+                    for (row in 0 until targetHeight) {
+                        buffer.position(row * rowStride)
+                        buffer.get(bytes, row * rowBytes, rowBytes)
+                    }
+                    bytes
+                }
+
+                bridge.pushFrame(rgbaBytes, targetWidth, targetHeight)
+                lastFrameTimeMs = now
+            } catch (e: Exception) {
+                Log.w(TAG, "Frame processing error: ${e.message}")
+            } finally {
+                image.close()
+            }
+        }, captureHandler)
+
+        virtualDisplay = projection.createVirtualDisplay(
+            VIRTUAL_DISPLAY_NAME,
+            targetWidth,
+            targetHeight,
+            metrics.densityDpi,
+            DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
+            imageReader?.surface,
+            null,
+            captureHandler,
+        )
+
+        Log.i(TAG, "Screen capture started (${targetWidth}x${targetHeight} @ ${targetFps}fps)")
+    }
+
+    /**
+     * Stop capturing and release all resources.
+     */
+    fun stop() {
+        running = false
+        // Order matters: detach the listener BEFORE releasing the
+        // VirtualDisplay so the handler can't be re-entered with stale
+        // resources, then quit & join the handler thread, only then
+        // close the ImageReader.
+        runCatching { imageReader?.setOnImageAvailableListener(null, null) }
+        runCatching { virtualDisplay?.release() }
+        virtualDisplay = null
+
+        captureThread?.quitSafely()
+        runCatching { captureThread?.join(500) }
+        captureThread = null
+        captureHandler = null
+
+        runCatching { imageReader?.close() }
+        imageReader = null
+
+        Log.i(TAG, "Screen capture stopped")
+    }
+}

android/app/src/main/java/com/ledgrab/android/UsbSerialBridge.kt

@@ -0,0 +1,288 @@
+package com.ledgrab.android
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.hardware.usb.UsbManager
+import android.os.Build
+import android.util.Log
+import com.hoho.android.usbserial.driver.UsbSerialDriver
+import com.hoho.android.usbserial.driver.UsbSerialPort
+import com.hoho.android.usbserial.driver.UsbSerialProber
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.TimeoutCancellationException
+
+/**
+ * USB-serial bridge exposed to the Python server via Chaquopy.
+ *
+ * Uses the `usb-serial-for-android` library (mik3y) which ships drivers
+ * for the common USB-to-TTL chips (CH340, CP2102, FTDI, Prolific, and
+ * CDC-ACM) found on Arduino boards and Adalight/AmbiLED controllers.
+ *
+ * Python callers access the singleton instance via
+ *   `UsbSerialBridge.INSTANCE.listDevices()` etc. — see
+ *   `server/src/ledgrab/core/devices/android_serial_transport.py`.
+ *
+ * The bridge holds no Context of its own; [init] must be called once
+ * from [LedGrabApp.onCreate] to bind the application context.
+ */
+object UsbSerialBridge {
+    private const val TAG = "UsbSerialBridge"
+    private const val ACTION_USB_PERMISSION = "com.ledgrab.android.USB_PERMISSION"
+
+    @Volatile private var appContext: Context? = null
+
+    private val handleSeq = AtomicInteger(1)
+    private val openPorts = HashMap<Int, UsbSerialPort>()
+    private val initialized = AtomicBoolean(false)
+    private val pendingPermissions = ConcurrentHashMap<String, CompletableDeferred<Boolean>>()
+
+    /** Called once from [LedGrabApp.onCreate] so we can resolve services. */
+    @JvmStatic
+    fun init(context: Context) {
+        val app = context.applicationContext
+        appContext = app
+        // Idempotent: re-entrant init() must not double-register the
+        // receiver (which would leak listeners and double-fire callbacks).
+        if (!initialized.compareAndSet(false, true)) return
+
+        val filter = IntentFilter(ACTION_USB_PERMISSION)
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(ctx: Context, intent: Intent) {
+                val granted = intent.getBooleanExtra(
+                    UsbManager.EXTRA_PERMISSION_GRANTED,
+                    false,
+                )
+                val device = intent.getParcelableExtra<android.hardware.usb.UsbDevice>(
+                    UsbManager.EXTRA_DEVICE,
+                )
+                Log.i(TAG, "USB permission broadcast: granted=$granted device=${device?.deviceName}")
+                device?.deviceName?.let { name ->
+                    pendingPermissions.remove(name)?.complete(granted)
+                }
+            }
+        }
+        // Android 14 requires RECEIVER_NOT_EXPORTED for non-system broadcasts.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            app.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED)
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            app.registerReceiver(receiver, filter)
+        }
+    }
+
+    private fun ctx(): Context =
+        appContext ?: error("UsbSerialBridge.init() not called — app context unavailable")
+
+    private fun safeSerial(driver: UsbSerialDriver): String =
+        try {
+            driver.device.serialNumber ?: ""
+        } catch (_: SecurityException) {
+            // Reading the serial requires USB permission on API 29+.
+            ""
+        }
+
+    /**
+     * Enumerate attached USB-serial devices.
+     *
+     * Each entry is `"VID|PID|serial|description"` with VID/PID as
+     * 4-char lowercase hex. Pipe is used as the separator so device
+     * descriptions containing colons (common on FTDI strings) don't
+     * confuse the Python parser.
+     */
+    @JvmStatic
+    fun listDevices(): List<String> {
+        val manager = ctx().getSystemService(Context.USB_SERVICE) as UsbManager
+        val drivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager)
+        return drivers.map { driver ->
+            val dev = driver.device
+            val vid = "%04x".format(dev.vendorId)
+            val pid = "%04x".format(dev.productId)
+            val serial = safeSerial(driver)
+            val description = buildString {
+                append(dev.manufacturerName ?: "USB")
+                val product = dev.productName
+                if (!product.isNullOrBlank()) {
+                    append(' ')
+                    append(product)
+                }
+            }.trim().ifEmpty { "USB $vid:$pid" }
+            "$vid|$pid|$serial|$description"
+        }
+    }
+
+    /**
+     * Open the first matching USB-serial device. Returns a non-negative
+     * opaque handle on success, -1 on failure (device not found, user
+     * denied permission, or driver error). Failures also trigger an
+     * async permission-request dialog when applicable — subsequent
+     * open() calls will succeed once the user grants.
+     */
+    @JvmStatic
+    fun open(vendorId: Int, productId: Int, serial: String, baud: Int): Int {
+        val context = ctx()
+        val manager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+        val drivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager)
+        val driver = drivers.firstOrNull { d ->
+            val dev = d.device
+            dev.vendorId == vendorId &&
+                dev.productId == productId &&
+                (serial.isEmpty() || safeSerial(d) == serial)
+        }
+        if (driver == null) {
+            Log.w(TAG, "No matching device for $vendorId:$productId:$serial")
+            return -1
+        }
+
+        if (!manager.hasPermission(driver.device)) {
+            Log.w(TAG, "USB permission not yet granted for ${driver.device.deviceName}")
+            requestPermission(context, manager, driver)
+            return -1
+        }
+
+        val connection = manager.openDevice(driver.device)
+        if (connection == null) {
+            Log.w(TAG, "openDevice returned null for ${driver.device.deviceName}")
+            return -1
+        }
+        val port = driver.ports.firstOrNull()
+        if (port == null) {
+            connection.close()
+            Log.w(TAG, "Driver reports no ports for ${driver.device.deviceName}")
+            return -1
+        }
+
+        try {
+            port.open(connection)
+            port.setParameters(
+                baud,
+                8,
+                UsbSerialPort.STOPBITS_1,
+                UsbSerialPort.PARITY_NONE,
+            )
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to configure serial port", e)
+            runCatching { port.close() }
+            return -1
+        }
+
+        val handle = handleSeq.getAndIncrement()
+        synchronized(openPorts) { openPorts[handle] = port }
+        Log.i(
+            TAG,
+            "Opened USB serial ${driver.device.deviceName} baud=$baud handle=$handle",
+        )
+        return handle
+    }
+
+    /** Write bytes to the previously-opened handle. Throws if invalid. */
+    @JvmStatic
+    fun write(handle: Int, data: ByteArray) {
+        val port = synchronized(openPorts) { openPorts[handle] }
+            ?: throw IllegalStateException("Invalid handle $handle")
+        // 1s write timeout matches the old pyserial `timeout=1` behavior.
+        port.write(data, 1_000)
+    }
+
+    /** Close a previously-opened handle. Silently ignores unknown handles. */
+    @JvmStatic
+    fun close(handle: Int) {
+        val port = synchronized(openPorts) { openPorts.remove(handle) } ?: return
+        runCatching { port.close() }
+            .onFailure { Log.w(TAG, "close($handle): ${it.message}") }
+    }
+
+    /**
+     * Block until the user grants (or denies) USB permission for the
+     * device with [deviceName] (e.g. "/dev/bus/usb/001/004"). Returns
+     * true if granted within [timeoutMs], false otherwise. Safe to call
+     * from a Python thread via Chaquopy.
+     */
+    @JvmStatic
+    @JvmOverloads
+    fun requestPermissionBlocking(deviceName: String, timeoutMs: Long = 15_000L): Boolean {
+        val context = ctx()
+        val manager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+        val driver = UsbSerialProber.getDefaultProber().findAllDrivers(manager)
+            .firstOrNull { it.device.deviceName == deviceName }
+            ?: return false
+        if (manager.hasPermission(driver.device)) return true
+
+        // Coalesce concurrent requests for the same device — only the
+        // first caller actually fires the system dialog.
+        val deferred = pendingPermissions.computeIfAbsent(deviceName) {
+            CompletableDeferred<Boolean>().also {
+                requestPermission(context, manager, driver)
+            }
+        }
+
+        return try {
+            runBlocking {
+                withTimeout(timeoutMs) { deferred.await() }
+            }
+        } catch (_: TimeoutCancellationException) {
+            pendingPermissions.remove(deviceName)
+            Log.w(TAG, "Permission request timed out for $deviceName")
+            false
+        } catch (e: Exception) {
+            pendingPermissions.remove(deviceName)
+            Log.w(TAG, "Permission request failed for $deviceName: ${e.message}")
+            false
+        }
+    }
+
+    /**
+     * Like [open] but blocks for permission first. Use this from Python
+     * instead of relying on the open()/retry pattern.
+     */
+    @JvmStatic
+    @JvmOverloads
+    fun openWithPermission(
+        vendorId: Int,
+        productId: Int,
+        serial: String,
+        baud: Int,
+        timeoutMs: Long = 15_000L,
+    ): Int {
+        val context = ctx()
+        val manager = context.getSystemService(Context.USB_SERVICE) as UsbManager
+        val driver = UsbSerialProber.getDefaultProber().findAllDrivers(manager)
+            .firstOrNull { d ->
+                val dev = d.device
+                dev.vendorId == vendorId &&
+                    dev.productId == productId &&
+                    (serial.isEmpty() || safeSerial(d) == serial)
+            } ?: return -1
+
+        if (!manager.hasPermission(driver.device)) {
+            val granted = requestPermissionBlocking(driver.device.deviceName, timeoutMs)
+            if (!granted) return -1
+        }
+        return open(vendorId, productId, serial, baud)
+    }
+
+    private fun requestPermission(
+        context: Context,
+        manager: UsbManager,
+        driver: UsbSerialDriver,
+    ) {
+        val flags =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+                PendingIntent.FLAG_IMMUTABLE
+            } else {
+                0
+            }
+        val intent = Intent(ACTION_USB_PERMISSION).apply {
+            setPackage(context.packageName)
+        }
+        val pending = PendingIntent.getBroadcast(context, 0, intent, flags)
+        manager.requestPermission(driver.device, pending)
+    }
+}

android/app/src/main/res/color/btn_secondary_text.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:state_focused="true" android:color="#ffffff" />
+    <item android:color="@color/purple_accent" />
+</selector>

android/app/src/main/res/drawable/bg_button_primary.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:state_focused="true">
+        <layer-list>
+            <item android:left="-6dp" android:top="-6dp" android:right="-6dp" android:bottom="-6dp">
+                <shape android:shape="rectangle">
+                    <solid android:color="#4064ffda" />
+                    <corners android:radius="44dp" />
+                </shape>
+            </item>
+            <item>
+                <shape android:shape="rectangle">
+                    <solid android:color="#64ffda" />
+                    <corners android:radius="36dp" />
+                </shape>
+            </item>
+        </layer-list>
+    </item>
+    <item android:state_pressed="true">
+        <shape android:shape="rectangle">
+            <solid android:color="#3dccb0" />
+            <corners android:radius="36dp" />
+        </shape>
+    </item>
+    <item>
+        <shape android:shape="rectangle">
+            <solid android:color="@color/teal_accent" />
+            <corners android:radius="36dp" />
+        </shape>
+    </item>
+</selector>

android/app/src/main/res/drawable/bg_button_secondary.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<selector xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:state_focused="true">
+        <layer-list>
+            <item android:left="-6dp" android:top="-6dp" android:right="-6dp" android:bottom="-6dp">
+                <shape android:shape="rectangle">
+                    <solid android:color="#40bb86fc" />
+                    <corners android:radius="44dp" />
+                </shape>
+            </item>
+            <item>
+                <shape android:shape="rectangle">
+                    <solid android:color="#7c4dff" />
+                    <corners android:radius="36dp" />
+                </shape>
+            </item>
+        </layer-list>
+    </item>
+    <item android:state_pressed="true">
+        <shape android:shape="rectangle">
+            <solid android:color="#9966d4" />
+            <corners android:radius="36dp" />
+            <stroke android:width="2dp" android:color="@color/purple_accent" />
+        </shape>
+    </item>
+    <item>
+        <shape android:shape="rectangle">
+            <solid android:color="#1Abb86fc" />
+            <corners android:radius="36dp" />
+            <stroke android:width="2dp" android:color="@color/purple_accent" />
+        </shape>
+    </item>
+</selector>

android/app/src/main/res/drawable/bg_main.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item>
+        <color android:color="@color/bg_navy" />
+    </item>
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:gradientRadius="900dp"
+                android:centerX="0.5"
+                android:centerY="-0.2"
+                android:startColor="#1A64ffda"
+                android:endColor="#000d1117" />
+        </shape>
+    </item>
+    <item>
+        <shape android:shape="rectangle">
+            <gradient
+                android:type="radial"
+                android:gradientRadius="600dp"
+                android:centerX="1.1"
+                android:centerY="1.2"
+                android:startColor="#12bb86fc"
+                android:endColor="#000d1117" />
+        </shape>
+    </item>
+</layer-list>

android/app/src/main/res/drawable/bg_qr_container.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:left="-8dp" android:top="-8dp" android:right="-8dp" android:bottom="-8dp">
+        <shape android:shape="rectangle">
+            <solid android:color="#2064ffda" />
+            <corners android:radius="24dp" />
+        </shape>
+    </item>
+    <item>
+        <shape android:shape="rectangle">
+            <solid android:color="#ffffff" />
+            <corners android:radius="16dp" />
+            <stroke android:width="3dp" android:color="@color/teal_accent" />
+        </shape>
+    </item>
+</layer-list>

android/app/src/main/res/drawable/bg_status_dot.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<shape xmlns:android="http://schemas.android.com/apk/res/android"
+    android:shape="oval">
+    <solid android:color="@color/green_status" />
+</shape>

android/app/src/main/res/drawable/bg_url_chip.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<shape xmlns:android="http://schemas.android.com/apk/res/android"
+    android:shape="rectangle">
+    <solid android:color="@color/bg_surface_elevated" />
+    <corners android:radius="12dp" />
+    <stroke android:width="1dp" android:color="#2264ffda" />
+</shape>

android/app/src/main/res/drawable/ic_launcher.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <!-- Background circle -->
+    <path
+        android:fillColor="#0d1117"
+        android:pathData="M54,54m-50,0a50,50 0,1 1,100 0a50,50 0,1 1,-100 0" />
+    <!-- Border ring -->
+    <path
+        android:strokeColor="#2264ffda"
+        android:strokeWidth="1.5"
+        android:fillColor="#00000000"
+        android:pathData="M54,54m-48,0a48,48 0,1 1,96 0a48,48 0,1 1,-96 0" />
+    <!-- TV body -->
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M26,32 L82,32 Q86,32 86,36 L86,68 Q86,72 82,72 L26,72 Q22,72 22,68 L22,36 Q22,32 26,32 Z" />
+    <!-- TV screen -->
+    <path
+        android:fillColor="#161b22"
+        android:pathData="M28,35 L80,35 Q82,35 82,37 L82,66 Q82,68 80,68 L28,68 Q26,68 26,66 L26,37 Q26,35 28,35 Z" />
+    <!-- LED glow - top (teal) -->
+    <path
+        android:fillColor="#64ffda"
+        android:fillAlpha="0.7"
+        android:pathData="M30,28 L78,28 L78,30 L30,30 Z" />
+    <!-- LED glow - left (purple) -->
+    <path
+        android:fillColor="#bb86fc"
+        android:fillAlpha="0.6"
+        android:pathData="M18,34 L20,34 L20,70 L18,70 Z" />
+    <!-- LED glow - right (red) -->
+    <path
+        android:fillColor="#ff6b6b"
+        android:fillAlpha="0.6"
+        android:pathData="M88,34 L90,34 L90,70 L88,70 Z" />
+    <!-- LED glow - bottom (yellow) -->
+    <path
+        android:fillColor="#ffd93d"
+        android:fillAlpha="0.6"
+        android:pathData="M30,74 L78,74 L78,76 L30,76 Z" />
+    <!-- TV stand -->
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M44,72 L44,78 L64,78 L64,72" />
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M38,78 L70,78 L70,80 L38,80 Z" />
+</vector>

android/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Adaptive icon foreground: TV with LED glow strips.
+     Centered in the 108dp safe zone (inner 72dp is guaranteed visible). -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <!-- TV body -->
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M26,32 L82,32 Q86,32 86,36 L86,68 Q86,72 82,72 L26,72 Q22,72 22,68 L22,36 Q22,32 26,32 Z" />
+    <!-- TV screen -->
+    <path
+        android:fillColor="#161b22"
+        android:pathData="M28,35 L80,35 Q82,35 82,37 L82,66 Q82,68 80,68 L28,68 Q26,68 26,66 L26,37 Q26,35 28,35 Z" />
+    <!-- LED glow - top (teal) -->
+    <path
+        android:fillColor="#64ffda"
+        android:fillAlpha="0.7"
+        android:pathData="M30,28 L78,28 L78,30 L30,30 Z" />
+    <!-- LED glow - left (purple) -->
+    <path
+        android:fillColor="#bb86fc"
+        android:fillAlpha="0.6"
+        android:pathData="M18,34 L20,34 L20,70 L18,70 Z" />
+    <!-- LED glow - right (red) -->
+    <path
+        android:fillColor="#ff6b6b"
+        android:fillAlpha="0.6"
+        android:pathData="M88,34 L90,34 L90,70 L88,70 Z" />
+    <!-- LED glow - bottom (yellow) -->
+    <path
+        android:fillColor="#ffd93d"
+        android:fillAlpha="0.6"
+        android:pathData="M30,74 L78,74 L78,76 L30,76 Z" />
+    <!-- TV stand -->
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M44,72 L44,78 L64,78 L64,72" />
+    <path
+        android:fillColor="#1c2333"
+        android:pathData="M38,78 L70,78 L70,80 L38,80 Z" />
+</vector>

android/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="utf-8"?>
+<FrameLayout
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:background="@drawable/bg_main">
+
+    <!-- STOPPED STATE -->
+    <LinearLayout
+        android:id="@+id/stopped_panel"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"
+        android:orientation="vertical"
+        android:gravity="center"
+        android:paddingStart="160dp"
+        android:paddingEnd="160dp">
+
+        <ImageView
+            android:layout_width="72dp"
+            android:layout_height="72dp"
+            android:src="@drawable/ic_launcher"
+            android:contentDescription="@null"
+            android:layout_marginBottom="24dp" />
+
+        <TextView
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:text="@string/app_name"
+            android:textColor="@color/teal_accent"
+            android:textSize="64sp"
+            android:textStyle="bold"
+            android:letterSpacing="0.08"
+            android:layout_marginBottom="12dp"
+            android:fontFamily="sans-serif-light" />
+
+        <TextView
+            android:id="@+id/status_text"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:text="@string/tagline"
+            android:textColor="@color/text_secondary"
+            android:textSize="28sp"
+            android:layout_marginBottom="64dp" />
+
+        <Button
+            android:id="@+id/toggle_button"
+            style="@style/Widget.LedGrab.Button.Primary"
+            android:layout_width="320dp"
+            android:layout_height="72dp"
+            android:text="@string/btn_start"
+            android:textSize="22sp"
+            android:focusable="true"
+            android:focusableInTouchMode="true" />
+
+        <CheckBox
+            android:id="@+id/autostart_check"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:layout_marginTop="32dp"
+            android:text="@string/autostart_label"
+            android:textColor="@color/text_secondary"
+            android:textSize="20sp"
+            android:buttonTint="@color/teal_accent"
+            android:focusable="true"
+            android:focusableInTouchMode="true" />
+    </LinearLayout>
+
+    <!-- Version at bottom -->
+    <TextView
+        android:id="@+id/version_text"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_gravity="bottom|center_horizontal"
+        android:layout_marginBottom="32dp"
+        android:textColor="@color/text_hint"
+        android:textSize="18sp"
+        tools:text="v0.1.0" />
+
+    <!-- RUNNING STATE -->
+    <LinearLayout
+        android:id="@+id/running_panel"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent"
+        android:orientation="horizontal"
+        android:gravity="center_vertical"
+        android:paddingStart="120dp"
+        android:paddingEnd="120dp"
+        android:paddingTop="80dp"
+        android:paddingBottom="80dp"
+        android:visibility="gone">
+
+        <!-- Left: status + URL + stop -->
+        <LinearLayout
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:orientation="vertical"
+            android:gravity="start|center_vertical"
+            android:paddingEnd="64dp">
+
+            <LinearLayout
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:orientation="horizontal"
+                android:gravity="center_vertical"
+                android:layout_marginBottom="32dp">
+
+                <View
+                    android:layout_width="18dp"
+                    android:layout_height="18dp"
+                    android:background="@drawable/bg_status_dot"
+                    android:layout_marginEnd="16dp" />
+
+                <TextView
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:text="@string/status_running"
+                    android:textColor="@color/green_status"
+                    android:textSize="28sp"
+                    android:textStyle="bold"
+                    android:letterSpacing="0.05" />
+            </LinearLayout>
+
+            <TextView
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:text="@string/label_web_ui"
+                android:textColor="@color/text_secondary"
+                android:textSize="22sp"
+                android:layout_marginBottom="8dp" />
+
+            <TextView
+                android:id="@+id/url_text"
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:textColor="@color/teal_accent"
+                android:textSize="30sp"
+                android:maxLines="1"
+                android:textStyle="bold"
+                android:background="@drawable/bg_url_chip"
+                android:paddingStart="24dp"
+                android:paddingEnd="24dp"
+                android:paddingTop="12dp"
+                android:paddingBottom="12dp"
+                android:layout_marginBottom="56dp"
+                tools:text="http://192.168.1.5:8080" />
+
+            <Button
+                android:id="@+id/stop_button_running"
+                style="@style/Widget.LedGrab.Button.Secondary"
+                android:layout_width="240dp"
+                android:layout_height="64dp"
+                android:text="@string/btn_stop"
+                android:textSize="20sp"
+                android:focusable="true"
+                android:focusableInTouchMode="true" />
+        </LinearLayout>
+
+        <!-- Right: QR code -->
+        <LinearLayout
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:orientation="vertical"
+            android:gravity="center">
+
+            <FrameLayout
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:background="@drawable/bg_qr_container"
+                android:padding="20dp"
+                android:layout_marginBottom="20dp">
+
+                <ImageView
+                    android:id="@+id/qr_image"
+                    android:layout_width="280dp"
+                    android:layout_height="280dp"
+                    android:contentDescription="@string/qr_description"
+                    android:scaleType="fitXY" />
+            </FrameLayout>
+
+            <TextView
+                android:layout_width="wrap_content"
+                android:layout_height="wrap_content"
+                android:text="@string/scan_to_configure"
+                android:textColor="@color/text_secondary"
+                android:textSize="22sp"
+                android:gravity="center" />
+        </LinearLayout>
+    </LinearLayout>
+</FrameLayout>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/bg_navy" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

android/app/src/main/res/values-ru/strings.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">LedGrab</string>
+    <string name="tagline">Фоновая подсветка для телевизора</string>
+    <string name="btn_start">Начать захват</string>
+    <string name="btn_stop">Стоп</string>
+    <string name="status_running">Работает</string>
+    <string name="label_web_ui">Адрес веб-интерфейса</string>
+    <string name="scan_to_configure">Сканируйте для настройки</string>
+    <string name="qr_description">QR-код для веб-интерфейса</string>
+    <string name="version_prefix">v%1$s</string>
+    <string name="autostart_label">Запускать при загрузке (только с root)</string>
+    <string name="autostart_unavailable">Запуск при загрузке — недоступно (нужен root)</string>
+</resources>

android/app/src/main/res/values-zh/strings.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">LedGrab</string>
+    <string name="tagline">电视氛围灯光</string>
+    <string name="btn_start">开始捕获</string>
+    <string name="btn_stop">停止</string>
+    <string name="status_running">运行中</string>
+    <string name="label_web_ui">Web界面地址</string>
+    <string name="scan_to_configure">扫码配置</string>
+    <string name="qr_description">Web界面二维码</string>
+    <string name="version_prefix">v%1$s</string>
+    <string name="autostart_label">开机自启(仅限 root)</string>
+    <string name="autostart_unavailable">开机自启 — 不可用(需要 root)</string>
+</resources>

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="bg_navy">#0d1117</color>
+    <color name="bg_navy_mid">#111827</color>
+    <color name="bg_surface">#161b22</color>
+    <color name="bg_surface_elevated">#1c2333</color>
+    <color name="teal_accent">#64ffda</color>
+    <color name="teal_accent_dim">#3399aa</color>
+    <color name="teal_accent_alpha30">#4D64ffda</color>
+    <color name="teal_accent_alpha15">#2664ffda</color>
+    <color name="purple_accent">#bb86fc</color>
+    <color name="purple_accent_dim">#7c4dff</color>
+    <color name="purple_accent_alpha30">#4Dbb86fc</color>
+    <color name="purple_accent_alpha15">#26bb86fc</color>
+    <color name="green_status">#4caf50</color>
+    <color name="green_status_dim">#1b5e20</color>
+    <color name="text_primary">#e6edf3</color>
+    <color name="text_secondary">#8b949e</color>
+    <color name="text_hint">#484f58</color>
+</resources>

android/app/src/main/res/values/strings.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">LedGrab</string>
+    <string name="tagline">Ambient lighting for your TV</string>
+    <string name="btn_start">Start Capture</string>
+    <string name="btn_stop">Stop</string>
+    <string name="status_running">Running</string>
+    <string name="label_web_ui">Web UI address</string>
+    <string name="scan_to_configure">Scan to configure</string>
+    <string name="qr_description">QR code for web UI</string>
+    <string name="version_prefix">v%1$s</string>
+    <string name="autostart_label">Start on boot (root only)</string>
+    <string name="autostart_unavailable">Start on boot — unavailable (root required)</string>
+</resources>

android/app/src/main/res/values/themes.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <style name="Theme.LedGrab" parent="@style/Theme.Leanback">
+        <item name="android:windowBackground">@color/bg_navy</item>
+        <item name="android:colorBackground">@color/bg_navy</item>
+        <item name="android:windowNoTitle">true</item>
+        <item name="android:textColorPrimary">@color/text_primary</item>
+        <item name="android:textColorSecondary">@color/text_secondary</item>
+        <item name="android:textColorHint">@color/text_hint</item>
+        <item name="android:colorAccent">@color/teal_accent</item>
+        <item name="android:colorControlHighlight">@color/teal_accent_dim</item>
+        <item name="android:colorControlActivated">@color/teal_accent</item>
+    </style>
+
+    <style name="Widget.LedGrab.Button.Primary" parent="@android:style/Widget.Button">
+        <item name="android:background">@drawable/bg_button_primary</item>
+        <item name="android:textColor">@color/bg_navy</item>
+        <item name="android:textStyle">bold</item>
+        <item name="android:focusable">true</item>
+        <item name="android:stateListAnimator">@null</item>
+    </style>
+
+    <style name="Widget.LedGrab.Button.Secondary" parent="@android:style/Widget.Button">
+        <item name="android:background">@drawable/bg_button_secondary</item>
+        <item name="android:textColor">@color/btn_secondary_text</item>
+        <item name="android:textStyle">bold</item>
+        <item name="android:focusable">true</item>
+        <item name="android:stateListAnimator">@null</item>
+    </style>
+</resources>

android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+    LedGrab communicates with WLED controllers, Home Assistant, and MQTT
+    brokers on the local network via plain HTTP/UDP.  Cleartext traffic
+    must be allowed for these connections to work on Android 9+.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="true" />
+</network-security-config>

android/build-scripts/build-pydantic-core.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+#
+# Cross-compile pydantic-core for Android across all three ABIs:
+#   arm64-v8a (primary — real TV hardware)
+#   x86_64    (modern emulators)
+#   x86       (legacy emulators)
+#
+# Outputs wheels into android/wheels/. Wheels are linked against the real
+# libpython3.11.so shipped by Chaquopy (stub .so does NOT work — see
+# memory/project_android_app.md for the incident notes).
+#
+# Prerequisites (on host):
+#   - Rust + cargo (rustup) with targets: aarch64/x86_64/i686-linux-android
+#   - Android NDK (ANDROID_NDK_HOME, or installed at Sdk/ndk/*)
+#   - Python 3.11 (matches Chaquopy's embedded version)
+#   - maturin (pip install maturin)
+#
+# Rebuild cadence: whenever PYDANTIC_CORE_VERSION changes, or pydantic's
+# core dependency version changes.
+#
+# Usage:
+#   ./build-pydantic-core.sh                 # build all three ABIs
+#   ./build-pydantic-core.sh arm64           # build a single ABI
+#   ./build-pydantic-core.sh arm64 x86_64    # build a subset
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ANDROID_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+WHEELS_DIR="$ANDROID_DIR/wheels"
+BUILD_DIR="$ANDROID_DIR/.build-cache"
+
+PYDANTIC_CORE_VERSION="2.46.0"
+API_LEVEL=24
+PY_VERSION="3.11"
+
+# Resolve a concrete python3.11 interpreter path (maturin needs it callable).
+# Windows Git Bash doesn't ship `python3.11` on PATH; fall back to `py -3.11`.
+if [ -z "${PYTHON_BIN:-}" ]; then
+    # Prefer `py -3.11` on Windows (Git Bash's `python3.11` resolves to a
+    # non-functional MSStore stub). Fall back to `python3.11` on Linux/macOS.
+    if command -v py >/dev/null 2>&1 && py -3.11 -c '' 2>/dev/null; then
+        PYTHON_BIN="$(py -3.11 -c 'import sys; print(sys.executable)' 2>/dev/null | tr -d '\r')"
+    elif command -v python3.11 >/dev/null 2>&1 && python3.11 -c '' 2>/dev/null; then
+        PYTHON_BIN="$(command -v python3.11)"
+    fi
+fi
+[ -n "${PYTHON_BIN:-}" ] || { echo "ERROR: python3.11 not found; set PYTHON_BIN"; exit 1; }
+echo "Python: $PYTHON_BIN"
+
+mkdir -p "$WHEELS_DIR"
+
+# ── Find Android NDK ────────────────────────────────────────────────
+if [ -z "${ANDROID_NDK_HOME:-}" ]; then
+    for candidate in \
+        "$HOME/Library/Android/sdk/ndk"/* \
+        "$HOME/Android/Sdk/ndk"/* \
+        "${LOCALAPPDATA:-}/Android/Sdk/ndk"/* \
+        "/c/Users/$(whoami)/AppData/Local/Android/Sdk/ndk"/* \
+        "/usr/local/lib/android/sdk/ndk"/* \
+        "${ANDROID_SDK_ROOT:-}/ndk"/*; do
+        if [ -d "$candidate" ]; then
+            ANDROID_NDK_HOME="$candidate"
+            break
+        fi
+    done
+fi
+[ -n "${ANDROID_NDK_HOME:-}" ] || { echo "ERROR: NDK not found; set ANDROID_NDK_HOME"; exit 1; }
+echo "NDK: $ANDROID_NDK_HOME"
+
+case "$(uname -s)" in
+    Linux*)               HOST_TAG="linux-x86_64" ;;
+    Darwin*)              HOST_TAG="darwin-x86_64" ;;
+    MINGW*|MSYS*|CYGWIN*) HOST_TAG="windows-x86_64" ;;
+    *) echo "Unsupported host OS"; exit 1 ;;
+esac
+TOOLCHAIN="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/$HOST_TAG"
+READELF="$TOOLCHAIN/bin/llvm-readelf"
+
+# ── Prepare source tree ─────────────────────────────────────────────
+SRC_DIR="$BUILD_DIR/pydantic_core-$PYDANTIC_CORE_VERSION"
+if [ ! -d "$SRC_DIR" ]; then
+    echo "Downloading pydantic_core $PYDANTIC_CORE_VERSION sdist..."
+    mkdir -p "$BUILD_DIR"
+    SDIST="$BUILD_DIR/pydantic_core-$PYDANTIC_CORE_VERSION.tar.gz"
+    [ -f "$SDIST" ] || curl -sSL --retry 3 -o "$SDIST" \
+        "https://files.pythonhosted.org/packages/source/p/pydantic_core/pydantic_core-$PYDANTIC_CORE_VERSION.tar.gz"
+    tar -xzf "$SDIST" -C "$BUILD_DIR"
+fi
+
+# ── ABI table ───────────────────────────────────────────────────────
+# Columns: short_name rust_target clang_prefix sysconfig_dir
+ABI_TABLE=(
+    "arm64   aarch64-linux-android  aarch64-linux-android${API_LEVEL}  cross-sysconfig"
+    "x86_64  x86_64-linux-android   x86_64-linux-android${API_LEVEL}   cross-sysconfig-x86_64"
+    "x86     i686-linux-android     i686-linux-android${API_LEVEL}     cross-sysconfig-x86"
+)
+
+declare -A ABI_TAG_MAP=(
+    [arm64]="arm64_v8a"
+    [x86_64]="x86_64"
+    [x86]="x86"
+)
+
+# ── Select which ABIs to build ──────────────────────────────────────
+SELECTED=("$@")
+if [ ${#SELECTED[@]} -eq 0 ]; then
+    SELECTED=(arm64 x86_64 x86)
+fi
+
+# ── Ensure rust targets are installed ───────────────────────────────
+for name in "${SELECTED[@]}"; do
+    for row in "${ABI_TABLE[@]}"; do
+        read -r sname rtarget _ _ <<<"$row"
+        if [ "$sname" = "$name" ]; then
+            rustup target add "$rtarget" >/dev/null 2>&1 || true
+        fi
+    done
+done
+
+# ── Build loop ──────────────────────────────────────────────────────
+cd "$SRC_DIR"
+
+for name in "${SELECTED[@]}"; do
+    MATCHED=""
+    for row in "${ABI_TABLE[@]}"; do
+        read -r sname rtarget cprefix sysdir <<<"$row"
+        if [ "$sname" = "$name" ]; then
+            MATCHED="1"
+            break
+        fi
+    done
+    [ -n "$MATCHED" ] || { echo "Unknown ABI: $name"; exit 1; }
+
+    CROSS_LIB_DIR="$BUILD_DIR/$sysdir"
+    [ -f "$CROSS_LIB_DIR/libpython3.11.so" ] || {
+        echo "ERROR: missing $CROSS_LIB_DIR/libpython3.11.so (extract from a Chaquopy APK)"
+        exit 1
+    }
+
+    # On Windows hosts the clang wrapper is a .cmd batch file; cargo/rustc
+    # can't exec it as a linker directly (os error 193). Use the .cmd path
+    # explicitly so CreateProcess picks up cmd.exe as interpreter.
+    CC_BIN="$TOOLCHAIN/bin/${cprefix}-clang"
+    if [ "$HOST_TAG" = "windows-x86_64" ] && [ -f "${CC_BIN}.cmd" ]; then
+        CC_BIN="${CC_BIN}.cmd"
+    fi
+    AR_BIN="$TOOLCHAIN/bin/llvm-ar"
+    [ "$HOST_TAG" = "windows-x86_64" ] && [ -f "${AR_BIN}.exe" ] && AR_BIN="${AR_BIN}.exe"
+    [ -f "$CC_BIN" ] || { echo "ERROR: $CC_BIN not found"; exit 1; }
+
+    # Normalize rust target name for env var (cargo wants UPPER_WITH_UNDERSCORES)
+    TARGET_ENV=$(echo "$rtarget" | tr 'a-z-' 'A-Z_')
+
+    echo ""
+    echo "════════════════════════════════════════════════════════════"
+    echo " Building pydantic_core $PYDANTIC_CORE_VERSION for $name ($rtarget)"
+    echo "════════════════════════════════════════════════════════════"
+
+    env \
+        CARGO_TARGET_DIR="$SRC_DIR/target" \
+        "CC_${rtarget//-/_}=$CC_BIN" \
+        "AR_${rtarget//-/_}=$AR_BIN" \
+        "CARGO_TARGET_${TARGET_ENV}_LINKER=$CC_BIN" \
+        PYO3_CROSS=1 \
+        PYO3_CROSS_LIB_DIR="$CROSS_LIB_DIR" \
+        PYO3_CROSS_PYTHON_VERSION="$PY_VERSION" \
+        RUSTFLAGS="-C link-arg=-Wl,--no-as-needed -C link-arg=-lpython3.11 -C link-arg=-L$CROSS_LIB_DIR" \
+        maturin build \
+            --release \
+            --target "$rtarget" \
+            --interpreter "$PYTHON_BIN" \
+            --out "$WHEELS_DIR" \
+            --compatibility linux
+
+    # maturin writes the wheel with the correct android_<api>_<abi> platform
+    # tag directly (the sysconfigdata provides MULTIARCH). Find + verify.
+    ABI_TAG="${ABI_TAG_MAP[$name]}"
+    OUT_WHL="$WHEELS_DIR/pydantic_core-$PYDANTIC_CORE_VERSION-cp311-cp311-android_${API_LEVEL}_${ABI_TAG}.whl"
+    [ -f "$OUT_WHL" ] || { echo "ERROR: expected wheel not found: $OUT_WHL"; exit 1; }
+
+    TMP=$(mktemp -d)
+    unzip -qo "$OUT_WHL" -d "$TMP" "pydantic_core/*.so"
+    SO=$(find "$TMP" -name "*.so" | head -1)
+    if "$READELF" -d "$SO" | grep -q "libpython3.11.so"; then
+        echo "  NEEDED OK: libpython3.11.so present in $(basename "$OUT_WHL")"
+    else
+        echo "  ERROR: libpython3.11.so NOT in NEEDED — wheel will crash at import"
+        "$READELF" -d "$SO" | grep NEEDED
+        rm -rf "$TMP"
+        exit 1
+    fi
+    rm -rf "$TMP"
+done
+
+echo ""
+echo "=== Build complete ==="
+ls -lh "$WHEELS_DIR"/pydantic_core-*.whl

android/build-scripts/setup-ndk.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+#
+# Set up the cross-compilation environment for building Python native
+# extensions targeting Android ARM64.
+#
+# This script:
+#   1. Verifies Android NDK is installed
+#   2. Installs the Rust aarch64-linux-android target
+#   3. Installs maturin (Python wheel builder for Rust extensions)
+#   4. Runs a quick test compile to verify the toolchain works
+#
+set -euo pipefail
+
+echo "=== LedGrab Android NDK Setup ==="
+
+# ── Check prerequisites ─────────────────────────────────────────────
+
+if ! command -v rustc &>/dev/null; then
+    echo "ERROR: Rust is not installed."
+    echo "Install from: https://rustup.rs/"
+    exit 1
+fi
+echo "Rust: $(rustc --version)"
+
+if ! command -v cargo &>/dev/null; then
+    echo "ERROR: Cargo is not installed."
+    exit 1
+fi
+echo "Cargo: $(cargo --version)"
+
+if ! command -v python3.11 &>/dev/null && ! command -v python3 &>/dev/null; then
+    echo "WARNING: Python 3.11 not found. Needed for maturin builds."
+fi
+
+# ── Install Rust target ─────────────────────────────────────────────
+
+echo ""
+echo "Installing Rust Android target..."
+rustup target add aarch64-linux-android
+echo "Installed targets:"
+rustup target list --installed | grep android
+
+# ── Install maturin ─────────────────────────────────────────────────
+
+echo ""
+echo "Installing maturin..."
+pip install maturin 2>/dev/null || pip3 install maturin 2>/dev/null || {
+    echo "WARNING: Could not install maturin. Install manually: pip install maturin"
+}
+
+if command -v maturin &>/dev/null; then
+    echo "maturin: $(maturin --version)"
+fi
+
+# ── Verify NDK ──────────────────────────────────────────────────────
+
+echo ""
+if [ -n "${ANDROID_NDK_HOME:-}" ]; then
+    echo "ANDROID_NDK_HOME: $ANDROID_NDK_HOME"
+else
+    echo "ANDROID_NDK_HOME is not set."
+    echo "Set it to your NDK installation path, e.g.:"
+    echo "  export ANDROID_NDK_HOME=\$HOME/Android/Sdk/ndk/26.1.10909125"
+    echo ""
+    echo "Or install NDK via Android Studio:"
+    echo "  SDK Manager → SDK Tools → NDK (Side by side)"
+fi
+
+echo ""
+echo "=== Setup complete ==="
+echo ""
+echo "Next steps:"
+echo "  1. Ensure ANDROID_NDK_HOME is set"
+echo "  2. Run: ./build-pydantic-core.sh"

android/build.gradle.kts

@@ -0,0 +1,5 @@
+plugins {
+    id("com.android.application") version "8.9.0" apply false
+    id("org.jetbrains.kotlin.android") version "2.1.0" apply false
+    id("com.chaquo.python") version "17.0.0" apply false
+}

android/gradle.properties

@@ -0,0 +1,7 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+kotlin.code.style=official
+android.nonTransitiveRClass=true
+org.gradle.parallel=false
+org.gradle.configuration-cache=false
+org.gradle.unsafe.isolated-projects=false

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

android/gradlew

@@ -0,0 +1,252 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

android/gradlew.bat

@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

android/settings.gradle.kts

@@ -0,0 +1,20 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+        // usb-serial-for-android (mik3y) is distributed via JitPack
+        maven { url = uri("https://jitpack.io") }
+    }
+}
+
+rootProject.name = "LedGrab"
+include(":app")

build/build-common.sh

@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+#
+# Shared build functions for LedGrab distribution packaging.
+# Sourced by build-dist.sh (Linux) and build-dist-windows.sh (Windows).
+#
+# Expected variables set by the caller before sourcing:
+#   SCRIPT_DIR, BUILD_DIR, DIST_DIR, SERVER_DIR, APP_DIR
+
+# ── Version detection ────────────────────────────────────────
+
+detect_version() {
+    # Usage: detect_version [explicit_version]
+    local 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/pyproject.toml" 2>/dev/null || echo "0.0.0")
+    fi
+
+    VERSION_CLEAN="${version#v}"
+
+    # Normalize non-PEP440 version labels (e.g. "dev", "nightly", "snapshot")
+    # to a valid PEP440 dev release. Without this, pip/setuptools rejects the
+    # pyproject.toml with: `project.version` must be pep440.
+    if ! [[ "$VERSION_CLEAN" =~ ^[0-9]+(\.[0-9]+)*((a|b|rc|\.dev|\.post)[0-9]+)*(\+[a-zA-Z0-9.]+)?$ ]]; then
+        echo "  Warning: '$VERSION_CLEAN' is not PEP440-compliant, using 0.0.0.dev0"
+        VERSION_CLEAN="0.0.0.dev0"
+    fi
+
+    # Stamp the resolved version into pyproject.toml so that
+    # importlib.metadata reads the correct value at runtime.
+    sed -i "s/^version = .*/version = \"${VERSION_CLEAN}\"/" "$SERVER_DIR/pyproject.toml"
+}
+
+# ── Clean previous build ─────────────────────────────────────
+
+clean_dist() {
+    if [ -d "$DIST_DIR" ]; then
+        echo "  Cleaning previous build..."
+        rm -rf "$DIST_DIR"
+    fi
+    mkdir -p "$DIST_DIR"
+}
+
+# ── Build frontend ───────────────────────────────────────────
+
+build_frontend() {
+    echo "  Building frontend bundle..."
+    (cd "$SERVER_DIR" && npm ci --loglevel error && npm run build) 2>&1 | {
+        grep -v 'RemoteException' || true
+    }
+}
+
+# ── Copy application files ───────────────────────────────────
+
+copy_app_files() {
+    echo "  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
+
+    # Patch the fallback version in the bundled __init__.py. Bundled installs
+    # strip ledgrab-*.dist-info from site-packages, so importlib.metadata
+    # falls back to this literal at runtime — and a stale literal is what
+    # silently shipped v0.4.2 reporting "0.3.0" in the WebUI.
+    local bundled_init="$APP_DIR/src/ledgrab/__init__.py"
+    if [ -f "$bundled_init" ] && [ -n "${VERSION_CLEAN:-}" ]; then
+        sed -i "s/_FALLBACK_VERSION = \"[^\"]*\"/_FALLBACK_VERSION = \"${VERSION_CLEAN}\"/" "$bundled_init"
+        echo "  Patched _FALLBACK_VERSION -> ${VERSION_CLEAN}"
+    fi
+}
+
+# ── Site-packages cleanup ────────────────────────────────────
+#
+# Strips tests, type stubs, unused submodules, and debug symbols
+# from the installed site-packages directory.
+#
+# Args:
+#   $1 — path to site-packages directory
+#   $2 — native extension suffix: "pyd" (Windows) or "so" (Linux)
+#   $3 — native lib suffix for OpenCV ffmpeg: "dll" or "so"
+
+cleanup_site_packages() {
+    local sp_dir="$1"
+    local ext_suffix="${2:-so}"
+    local lib_suffix="${3:-so}"
+
+    echo "  Cleaning up site-packages to reduce size..."
+
+    # ── Generic cleanup ──────────────────────────────────────
+    find "$sp_dir" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -type d -name tests -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -type d -name test -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -type d -name "*.dist-info" -exec rm -rf {} + 2>/dev/null || true
+    find "$sp_dir" -name "*.pyi" -delete 2>/dev/null || true
+
+    # ── pip / setuptools (not needed at runtime) ─────────────
+    rm -rf "$sp_dir"/pip "$sp_dir"/pip-* 2>/dev/null || true
+    rm -rf "$sp_dir"/setuptools "$sp_dir"/setuptools-* "$sp_dir"/pkg_resources 2>/dev/null || true
+    rm -rf "$sp_dir"/_distutils_hack 2>/dev/null || true
+
+    # ── OpenCV ───────────────────────────────────────────────
+    local cv2_dir="$sp_dir/cv2"
+    if [ -d "$cv2_dir" ]; then
+        # Remove ffmpeg (28 MB on Windows), Haar cascades, dev files
+        rm -f "$cv2_dir"/opencv_videoio_ffmpeg*."$lib_suffix" 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 ────────────────────────────────────────────────
+    # Only strip modules that are safely unused by numpy's own import chain.
+    # DO NOT strip: lib, linalg, ma, matrixlib — numpy.__init__ imports them
+    # transitively (e.g. matrixlib → defmatrix → linalg), so removing any of
+    # these breaks `import numpy` itself, cascading into every downstream
+    # module. Learned the hard way in the v0.0.0.dev0 Windows build.
+    for mod in polynomial distutils f2py typing _pyinstaller; do
+        rm -rf "$sp_dir/numpy/$mod" 2>/dev/null || true
+    done
+    rm -rf "$sp_dir/numpy/tests" "$sp_dir/numpy/*/tests" 2>/dev/null || true
+
+    # ── Pillow (only used for system tray icon) ──────────────
+    rm -rf "$sp_dir/PIL/tests" 2>/dev/null || true
+    # Remove unused image format plugins (keep JPEG, PNG, ICO, BMP)
+    for plugin in Eps Gif Tiff Webp Psd Pcx Xbm Xpm Dds Ftex Gbr Grib \
+                  Icns Im Imt Iptc McIrdas Mpo Msp Pcd Pixar Ppm Sgi \
+                  Spider Sun Tga Wal Wmf; do
+        rm -f "$sp_dir/PIL/${plugin}ImagePlugin.py" 2>/dev/null || true
+        rm -f "$sp_dir/PIL/${plugin}ImagePlugin.pyc" 2>/dev/null || true
+    done
+
+    # ── zeroconf ─────────────────────────────────────────────
+    # DO NOT strip zeroconf/_services — the compiled Cython _listener.pyd
+    # imports from it, and the import fails at runtime with:
+    # ModuleNotFoundError: No module named 'zeroconf._services'
+    # Same class of bug as numpy — "presumed unused" submodule is actually
+    # imported internally by the package's own compiled code.
+
+    # ── Strip debug symbols ──────────────────────────────────
+    if command -v strip &>/dev/null; then
+        echo "  Stripping debug symbols from .$ext_suffix files..."
+        find "$sp_dir" -name "*.$ext_suffix" -exec strip --strip-debug {} \; 2>/dev/null || true
+    fi
+
+    # ── Remove ledgrab if pip-installed ───────────────
+    rm -rf "$sp_dir"/ledgrab* "$sp_dir"/ledgrab*.dist-info 2>/dev/null || true
+
+    local cleaned_size
+    cleaned_size=$(du -sh "$sp_dir" | cut -f1)
+    echo "  Site-packages after cleanup: $cleaned_size"
+}
+
+# ── Pre-compile .py → .pyc (keep sources) ────────────────────
+#
+# MUST run AFTER cleanup_site_packages. Speeds up first startup by
+# producing .pyc alongside .py. We deliberately do NOT delete .py
+# sources afterwards:
+#
+#   1. OpenCV's loader does literal file I/O on cv2/config.py (not
+#      an import) — stripping it breaks `import cv2` with:
+#      "OpenCV loader: missing configuration file: ['config.py']".
+#   2. Other packages may do similar tricks (inspect.getsource,
+#      runtime introspection, __file__-relative data loading).
+#   3. The size saving (~30%) isn't worth the whack-a-mole of
+#      shipping broken installers. We already hit this with
+#      numpy.linalg and zeroconf._services — enough incidents.
+#
+# Args:
+#   $1 — directory to compile (site-packages or app/src)
+#   $2 — python executable to use (default: python3)
+
+compile_and_strip_sources() {
+    local target_dir="$1"
+    local py_cmd="${2:-python3}"
+
+    if [ ! -d "$target_dir" ]; then
+        return 0
+    fi
+
+    echo "  Pre-compiling Python bytecode in $(basename "$target_dir")..."
+    "$py_cmd" -m compileall -b -q "$target_dir" 2>/dev/null || {
+        echo "  ERROR: compileall failed for $target_dir — aborting"
+        return 1
+    }
+    # Drop __pycache__ to save the duplicated PEP-3147 copies; the
+    # `-b` flag above placed legacy .pyc next to each .py, so nothing
+    # of value is lost here.
+    find "$target_dir" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+}
+
+# ── Import smoke test ────────────────────────────────────────
+#
+# Verifies that every top-level dependency that ledgrab actually
+# uses can be imported from the stripped site-packages. Catches regressions
+# where cleanup_site_packages removes a submodule that turns out to be
+# imported internally by the package (e.g. numpy.linalg, zeroconf._services).
+# Failing here is cheap; failing on a user's machine after install is not.
+#
+# Args:
+#   $1 — path to site-packages to test against
+#   $2 — python executable
+#   $3 — (optional) extra PYTHONPATH entry (e.g. app/src for ledgrab)
+
+smoke_test_imports() {
+    local sp_dir="$1"
+    local py_cmd="${2:-python3}"
+    local extra_path="${3:-}"
+
+    echo "  Running import smoke test..."
+    local pypath="$sp_dir"
+    if [ -n "$extra_path" ]; then
+        pypath="$extra_path:$sp_dir"
+    fi
+
+    # Modules that MUST import cleanly IF PRESENT. We don't enforce
+    # installation — Pillow for example is only a Windows dep. But if a
+    # module's top-level package dir exists in site-packages and we
+    # can't import it, that's a broken install and we abort.
+    local smoke_script
+    smoke_script=$(cat <<'PYEOF'
+import importlib
+import os
+import sys
+
+sp_dir = sys.argv[1]
+
+# (module_name, site-packages path to check for presence)
+candidates = [
+    ('numpy', 'numpy'),
+    ('numpy.linalg', 'numpy/linalg'),
+    ('numpy.lib', 'numpy/lib'),
+    ('numpy.matrixlib', 'numpy/matrixlib'),
+    ('cv2', 'cv2'),
+    ('fastapi', 'fastapi'),
+    ('uvicorn', 'uvicorn'),
+    ('starlette', 'starlette'),
+    ('pydantic', 'pydantic'),
+    ('zeroconf', 'zeroconf'),
+    ('zeroconf._services', 'zeroconf/_services'),
+    ('PIL', 'PIL'),
+    ('PIL.Image', 'PIL'),
+    ('yaml', 'yaml'),
+]
+
+tested = 0
+skipped = 0
+failed = []
+for mod, path in candidates:
+    if not os.path.exists(os.path.join(sp_dir, path)):
+        skipped += 1
+        continue
+    try:
+        importlib.import_module(mod)
+        tested += 1
+    except Exception as e:
+        failed.append(f'{mod}: {type(e).__name__}: {e}')
+
+if failed:
+    print('SMOKE TEST FAILED:', file=sys.stderr)
+    for f in failed:
+        print(f'  {f}', file=sys.stderr)
+    sys.exit(1)
+
+print(f'  Smoke test passed ({tested} imported, {skipped} not installed)')
+PYEOF
+)
+
+    if ! PYTHONPATH="$pypath" "$py_cmd" -c "$smoke_script" "$sp_dir"; then
+        echo "  ERROR: smoke test failed — site-packages is broken, aborting build"
+        return 1
+    fi
+}

build/build-dist-windows.sh

@@ -14,35 +14,22 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-BUILD_DIR="$SCRIPT_DIR/build"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BUILD_DIR="$SCRIPT_DIR"
 DIST_NAME="LedGrab"
 DIST_DIR="$BUILD_DIR/$DIST_NAME"
-SERVER_DIR="$SCRIPT_DIR/server"
+SERVER_DIR="$REPO_ROOT/server"
 PYTHON_DIR="$DIST_DIR/python"
 APP_DIR="$DIST_DIR/app"
 PYTHON_VERSION="${PYTHON_VERSION:-3.11.9}"
 
+source "$SCRIPT_DIR/build-common.sh"
+
 # ── 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/pyproject.toml" 2>/dev/null || echo "0.0.0")
-fi
-
-VERSION_CLEAN="${VERSION#v}"
+detect_version "${1:-}"
 ZIP_NAME="LedGrab-v${VERSION_CLEAN}-win-x64.zip"
 
-# Stamp the resolved version into pyproject.toml so that
-# importlib.metadata reads the correct value at runtime.
-sed -i "s/^version = .*/version = \"${VERSION_CLEAN}\"/" "$SERVER_DIR/pyproject.toml"
-
 echo "=== Cross-building LedGrab v${VERSION_CLEAN} (Windows from Linux) ==="
 echo "  Embedded Python: $PYTHON_VERSION"
 echo "  Output: build/$ZIP_NAME"
@@ -50,11 +37,8 @@ echo ""
 
 # ── Clean ────────────────────────────────────────────────────
 
-if [ -d "$DIST_DIR" ]; then
-    echo "[1/9] Cleaning previous build..."
-    rm -rf "$DIST_DIR"
-fi
-mkdir -p "$DIST_DIR"
+echo "[1/9] Cleaning..."
+clean_dist
 
 # ── Download Windows embedded Python ─────────────────────────
 
@@ -83,7 +67,7 @@ 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
+# source directory here for ledgrab to be importable
 if ! grep -q '\.\./app/src' "$PTH_FILE"; then
     echo '../app/src' >> "$PTH_FILE"
 fi
@@ -194,16 +178,18 @@ 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.
+# Core dependencies (cross-platform, should have win_amd64 wheels).
+# KEEP IN SYNC with server/pyproject.toml [project.dependencies] — this
+# list duplicates it because cross-build on Linux can't invoke `pip install
+# <path>` against pyproject.toml with a Windows target. Missing entries
+# ship a broken installer that silently fails under pythonw.exe (no
+# traceback visible to the user). Audit after every pyproject.toml edit.
 DEPS=(
     "fastapi>=0.115.0"
     "uvicorn[standard]>=0.32.0"
+    "cryptography>=42.0.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"
@@ -220,8 +206,8 @@ DEPS=(
     "sounddevice>=0.5"
     "aiomqtt>=2.0.0"
     "openrgb-python>=0.2.15"
-    # camera extra
     "opencv-python-headless>=4.8.0"
+    "just-playback>=0.1.7"
 )
 
 # Windows-only deps
@@ -232,8 +218,13 @@ WIN_DEPS=(
     "winrt-Windows.Foundation>=3.0.0"
     "winrt-Windows.Foundation.Collections>=3.0.0"
     "winrt-Windows.ApplicationModel>=3.0.0"
-    # System tray
+    # System tray (Pillow needed by pystray for tray icon)
     "pystray>=0.19.0"
+    "Pillow>=10.4.0"
+    # Windows screen capture engines (mss is the only fallback without these)
+    "dxcam>=0.0.5"
+    "bettercam>=1.0.0"
+    "windows-capture>=1.5.0"
 )
 
 # Download cross-platform deps (prefer binary, allow source for pure Python)
@@ -286,78 +277,52 @@ for sdist in "$WHEEL_DIR"/*.tar.gz; do
 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
+cleanup_site_packages "$SITE_PACKAGES" "pyd" "dll"
 
-# 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)
+# Windows-specific cleanup
 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
+# Pre-compile and strip .py sources. MUST run AFTER cleanup (so we don't
+# waste work compiling files about to be deleted). Uses host python —
+# PYTHON_VERSION above must match the embedded Python major.minor or
+# the generated .pyc will ImportError on the target.
+compile_and_strip_sources "$SITE_PACKAGES" "python"
 
-CLEANED_SIZE=$(du -sh "$SITE_PACKAGES" | cut -f1)
-echo "  Site-packages after cleanup: $CLEANED_SIZE"
+# Windows cross-build: host python can't load win_amd64 .pyd files, so
+# we can't `import numpy` for real. Instead, check that the submodules
+# known to be imported internally exist on disk — the same landmines that
+# cost users a broken v0.0.0.dev0 installer.
+echo "  Verifying required submodules exist after cleanup..."
+for required in \
+    "numpy/linalg" "numpy/lib" "numpy/matrixlib" "numpy/ma" \
+    "zeroconf/_services" \
+    "cryptography" "cffi" "just_playback"; do
+    if [ ! -d "$SITE_PACKAGES/$required" ] && [ ! -f "$SITE_PACKAGES/$required.py" ] && [ ! -f "$SITE_PACKAGES/$required.pyc" ]; then
+        echo "  ERROR: $required missing from site-packages — either cleanup_site_packages removed something required, or DEPS is out of sync with pyproject.toml. Aborting."
+        exit 1
+    fi
+done
+echo "  All required submodules present."
 
 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
-}
+echo "[7/9] Building frontend..."
+build_frontend
 
 # ── Copy application files ───────────────────────────────────
 
 echo "[8/9] Copying application files..."
-mkdir -p "$APP_DIR"
+copy_app_files
 
-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..."
+# Pre-compile app source for faster startup (keep .py too — app source
+# is small and easier to debug in-place if a user reports an issue)
 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 ──────────────────────────────────────────
 
@@ -369,14 +334,20 @@ cd /d "%~dp0"
 
 :: Set paths
 set PYTHONPATH=%~dp0app\src
-set WLED_CONFIG_PATH=%~dp0app\config\default_config.yaml
+set LEDGRAB_CONFIG_PATH=%~dp0app\config\default_config.yaml
+
+:: Tcl/Tk ship under python\ but Tk's default search path is
+:: <python.exe>\..\lib\tcl8.6. Point it at the right location so
+:: the screen-overlay feature (tkinter) can start without errors.
+set TCL_LIBRARY=%~dp0python\tcl8.6
+set TK_LIBRARY=%~dp0python\tk8.6
 
 :: Create data directory if missing
 if not exist "%~dp0data" mkdir "%~dp0data"
 if not exist "%~dp0logs" mkdir "%~dp0logs"
 
 :: Start the server (tray icon handles UI and exit)
-"%~dp0python\pythonw.exe" -m wled_controller
+"%~dp0python\pythonw.exe" -m ledgrab
 LAUNCHER
 
 # Convert launcher to Windows line endings
@@ -384,7 +355,7 @@ sed -i 's/$/\r/' "$DIST_DIR/LedGrab.bat"
 
 # Copy hidden launcher VBS
 mkdir -p "$DIST_DIR/scripts"
-cp server/scripts/start-hidden.vbs "$DIST_DIR/scripts/"
+cp "$SERVER_DIR/scripts/start-hidden.vbs" "$DIST_DIR/scripts/"
 
 # ── Create autostart scripts ─────────────────────────────────
 

build/build-dist.ps1

@@ -34,11 +34,11 @@ param(
 $ErrorActionPreference = 'Stop'
 $ProgressPreference = 'SilentlyContinue'  # faster downloads
 
-$ScriptRoot = $PSScriptRoot
-$BuildDir = Join-Path $ScriptRoot "build"
+$RepoRoot = Split-Path $PSScriptRoot -Parent
+$BuildDir = $PSScriptRoot
 $DistName = "LedGrab"
 $DistDir = Join-Path $BuildDir $DistName
-$ServerDir = Join-Path $ScriptRoot "server"
+$ServerDir = Join-Path $RepoRoot "server"
 $PythonDir = Join-Path $DistDir "python"
 $AppDir = Join-Path $DistDir "app"
 
@@ -58,7 +58,7 @@ if (-not $Version) {
 }
 if (-not $Version) {
     # Parse from __init__.py
-    $initFile = Join-Path $ServerDir "src\wled_controller\__init__.py"
+    $initFile = Join-Path $ServerDir "src\ledgrab\__init__.py"
     $match = Select-String -Path $initFile -Pattern '__version__\s*=\s*"([^"]+)"'
     if ($match) { $Version = $match.Matches[0].Groups[1].Value }
 }
@@ -107,7 +107,7 @@ 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
+# directly for ledgrab to be importable
 if ($pthContent -notmatch '\.\.[/\\]app[/\\]src') {
     $pthContent = $pthContent.TrimEnd() + "`n..\app\src`n"
 }
@@ -130,7 +130,7 @@ if ($LASTEXITCODE -ne 0) { throw "Failed to install pip" }
 # ── Install dependencies ──────────────────────────────────────
 
 Write-Host "[5/8] Installing dependencies..."
-$extras = "camera,notifications,tray"
+$extras = "camera,notifications"
 if (-not $SkipPerf) { $extras += ",perf" }
 
 # Install the project (pulls all deps via pyproject.toml), then remove
@@ -144,10 +144,10 @@ if ($LASTEXITCODE -ne 0) {
     Write-Host "  Some optional deps may have failed (continuing)..." -ForegroundColor Yellow
 }
 
-# Remove the installed wled_controller package to avoid duplication
+# Remove the installed ledgrab 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
+Get-ChildItem -Path $sitePackages -Filter "ledgrab*" -Directory | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
+Get-ChildItem -Path $sitePackages -Filter "ledgrab*.dist-info" -Directory | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
 
 # Clean up caches and test files to reduce size
 Write-Host "  Cleaning up caches..."
@@ -196,6 +196,17 @@ New-Item -ItemType Directory -Path (Join-Path $DistDir "logs") -Force | Out-Null
 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
 
+# Patch the fallback version in the bundled __init__.py so the WebUI always
+# reports the release version — the installer strips ledgrab-*.dist-info from
+# site-packages (above), so importlib.metadata falls back to this literal.
+$bundledInit = Join-Path $srcDest "ledgrab\__init__.py"
+if (Test-Path $bundledInit) {
+    $initContent = Get-Content $bundledInit -Raw
+    $patched = [regex]::Replace($initContent, '_FALLBACK_VERSION\s*=\s*"[^"]*"', "_FALLBACK_VERSION = `"$VersionClean`"")
+    Set-Content -Path $bundledInit -Value $patched -NoNewline
+    Write-Host "  Patched _FALLBACK_VERSION -> $VersionClean"
+}
+
 # ── Create launcher ────────────────────────────────────────────
 
 Write-Host "[8/8] Creating launcher..."
@@ -206,14 +217,20 @@ cd /d "%~dp0"
 
 :: Set paths
 set PYTHONPATH=%~dp0app\src
-set WLED_CONFIG_PATH=%~dp0app\config\default_config.yaml
+set LEDGRAB_CONFIG_PATH=%~dp0app\config\default_config.yaml
+
+:: Tcl/Tk ship under python\ but Tk's default search path is
+:: <python.exe>\..\lib\tcl8.6. Point it at the right location so
+:: the screen-overlay feature (tkinter) can start without errors.
+set TCL_LIBRARY=%~dp0python\tcl8.6
+set TK_LIBRARY=%~dp0python\tk8.6
 
 :: Create data directory if missing
 if not exist "%~dp0data" mkdir "%~dp0data"
 if not exist "%~dp0logs" mkdir "%~dp0logs"
 
 :: Start the server (tray icon handles UI and exit)
-"%~dp0python\pythonw.exe" -m wled_controller
+"%~dp0python\pythonw.exe" -m ledgrab
 '@
 
 $launcherContent = $launcherContent -replace '%VERSION%', $VersionClean

build/build-dist.sh

@@ -10,45 +10,29 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-BUILD_DIR="$SCRIPT_DIR/build"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BUILD_DIR="$SCRIPT_DIR"
 DIST_NAME="LedGrab"
 DIST_DIR="$BUILD_DIR/$DIST_NAME"
-SERVER_DIR="$SCRIPT_DIR/server"
+SERVER_DIR="$REPO_ROOT/server"
 VENV_DIR="$DIST_DIR/venv"
 APP_DIR="$DIST_DIR/app"
 
+source "$SCRIPT_DIR/build-common.sh"
+
 # ── 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/pyproject.toml" 2>/dev/null || echo "0.0.0")
-fi
-
-VERSION_CLEAN="${VERSION#v}"
+detect_version "${1:-}"
 TAR_NAME="LedGrab-v${VERSION_CLEAN}-linux-x64.tar.gz"
 
-# Stamp the resolved version into pyproject.toml so that
-# importlib.metadata reads the correct value at runtime.
-sed -i "s/^version = .*/version = \"${VERSION_CLEAN}\"/" "$SERVER_DIR/pyproject.toml"
-
 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"
+echo "[1/7] Cleaning..."
+clean_dist
 
 # ── Create virtualenv ────────────────────────────────────────
 
@@ -60,38 +44,35 @@ pip install --upgrade pip --quiet
 # ── Install dependencies ─────────────────────────────────────
 
 echo "[3/7] Installing dependencies..."
-pip install --quiet "${SERVER_DIR}[camera,notifications]" 2>&1 | {
+pip install --quiet "${SERVER_DIR}[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
+# Resolve site-packages path (glob expand)
+SITE_PACKAGES=$(echo "$VENV_DIR"/lib/python*/site-packages)
 
-# 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
+# Clean up with shared function
+cleanup_site_packages "$SITE_PACKAGES" "so" "so"
+
+# Pre-compile and strip .py sources (must happen AFTER cleanup)
+compile_and_strip_sources "$SITE_PACKAGES" "python"
+
+# Fail loud if cleanup broke any required import
+smoke_test_imports "$SITE_PACKAGES" "python"
 
 # ── Build frontend ───────────────────────────────────────────
 
-echo "[4/7] Building frontend bundle..."
-(cd "$SERVER_DIR" && npm ci --loglevel error && npm run build) 2>&1 | {
-    grep -v 'RemoteException' || true
-}
+echo "[4/7] Building frontend..."
+build_frontend
 
 # ── Copy application files ───────────────────────────────────
 
 echo "[5/7] Copying application files..."
-mkdir -p "$APP_DIR"
+copy_app_files
 
-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 app source for faster startup (keep .py too — app source
+# is small and easier to debug in-place if a user reports an issue)
+python -m compileall -b -q "$APP_DIR/src" 2>/dev/null || true
 
 # ── Create launcher ──────────────────────────────────────────
 
@@ -103,12 +84,12 @@ 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"
+export LEDGRAB_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
+exec python -m ledgrab.main
 LAUNCHER
 
 sed -i "s/VERSION_PLACEHOLDER/${VERSION_CLEAN}/" "$DIST_DIR/run.sh"

build/installer.nsi

@@ -22,7 +22,7 @@
 !endif
 
 Name "${APPNAME} v${VERSION}"
-OutFile "build\${APPNAME}-v${VERSION}-win-x64-setup.exe"
+OutFile "${APPNAME}-v${VERSION}-win-x64-setup.exe"
 InstallDir "$LOCALAPPDATA\${APPNAME}"
 InstallDirRegKey HKCU "Software\${APPNAME}" "InstallDir"
 RequestExecutionLevel user
@@ -30,6 +30,8 @@ SetCompressor /SOLID lzma
 
 ; ── Modern UI Configuration ─────────────────────────────────
 
+!define MUI_ICON "..\server\src\ledgrab\static\icons\icon.ico"
+!define MUI_UNICON "..\server\src\ledgrab\static\icons\icon.ico"
 !define MUI_ABORTWARNING
 
 ; ── Pages ───────────────────────────────────────────────────
@@ -85,11 +87,29 @@ Section "!${APPNAME} (required)" SecCore
 
   SetOutPath "$INSTDIR"
 
+  ; Wipe prior payload dirs before extracting. NSIS File /r MERGES files
+  ; on top of existing ones — on an upgrade, stale .pyc/.pyd from the old
+  ; version (and any files removed or renamed since) would survive,
+  ; producing a half-old/half-new install that presents as "version
+  ; mismatch" or "duplicate package" ImportErrors at runtime.
+  ; IMPORTANT: only touch payload dirs — never $INSTDIR\data or
+  ; $INSTDIR\logs (user config must be preserved across upgrades).
+  RMDir /r "$INSTDIR\python"
+  RMDir /r "$INSTDIR\app"
+  RMDir /r "$INSTDIR\scripts"
+  Delete "$INSTDIR\LedGrab.bat"
+  ; Legacy leftovers from the wled_controller-era install. The current
+  ; build does not ship debug.bat, but upgrades from older versions left
+  ; one behind with a stale `-m wled_controller` command that gives a
+  ; misleading ModuleNotFoundError when run. Remove it on upgrade.
+  Delete "$INSTDIR\debug.bat"
+  Delete "$INSTDIR\debug.log"
+
   ; Copy the entire portable build
-  File /r "build\LedGrab\python"
-  File /r "build\LedGrab\app"
-  File /r "build\LedGrab\scripts"
-  File "build\LedGrab\LedGrab.bat"
+  File /r "LedGrab\python"
+  File /r "LedGrab\app"
+  File /r "LedGrab\scripts"
+  File "LedGrab\LedGrab.bat"
 
   ; Create data and logs directories
   CreateDirectory "$INSTDIR\data"
@@ -102,7 +122,7 @@ Section "!${APPNAME} (required)" SecCore
   CreateDirectory "$SMPROGRAMS\${APPNAME}"
   CreateShortcut "$SMPROGRAMS\${APPNAME}\${APPNAME}.lnk" \
     "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
-    "$INSTDIR\python\pythonw.exe" 0
+    "$INSTDIR\app\src\ledgrab\static\icons\icon.ico" 0
   CreateShortcut "$SMPROGRAMS\${APPNAME}\Uninstall.lnk" "$INSTDIR\uninstall.exe"
 
   ; Registry: install location + Add/Remove Programs entry
@@ -117,10 +137,12 @@ Section "!${APPNAME} (required)" SecCore
     "UninstallString" '"$INSTDIR\uninstall.exe"'
   WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
     "InstallLocation" "$INSTDIR"
+  WriteRegStr HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
+    "DisplayIcon" "$INSTDIR\app\src\ledgrab\static\icons\icon.ico"
   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"
+    "URLInfoAbout" "https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab"
   WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
     "NoModify" 1
   WriteRegDWORD HKCU "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" \
@@ -136,13 +158,16 @@ SectionEnd
 Section "Desktop shortcut" SecDesktop
   CreateShortcut "$DESKTOP\${APPNAME}.lnk" \
     "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
-    "$INSTDIR\python\pythonw.exe" 0
+    "$INSTDIR\app\src\ledgrab\static\icons\icon.ico" 0
 SectionEnd
 
 Section "Start with Windows" SecAutostart
+  ; Pass --autostart so the VBS sets LEDGRAB_AUTOSTART=1 and the app suppresses
+  ; the browser auto-open on Windows login. Manual launches (desktop / start
+  ; menu) don't pass the arg, so they keep opening the WebUI tab.
   CreateShortcut "$SMSTARTUP\${APPNAME}.lnk" \
-    "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"' \
-    "$INSTDIR\python\pythonw.exe" 0
+    "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}" --autostart' \
+    "$INSTDIR\app\src\ledgrab\static\icons\icon.ico" 0
 SectionEnd
 
 ; ── Section Descriptions ────────────────────────────────────
@@ -171,6 +196,8 @@ Section "Uninstall"
   RMDir /r "$INSTDIR\app"
   RMDir /r "$INSTDIR\scripts"
   Delete "$INSTDIR\LedGrab.bat"
+  Delete "$INSTDIR\debug.bat"
+  Delete "$INSTDIR\debug.log"
   Delete "$INSTDIR\uninstall.exe"
 
   ; Remove logs (but keep data/)

contexts/auto-update-plan.md

@@ -1,143 +0,0 @@
-# Auto-Update Plan — Phase 1: Check & Notify
-
-> Created: 2026-03-25. Status: **planned, not started.**
-
-## Backend Architecture
-
-### Release Provider Abstraction
-
-```
-core/update/
-    release_provider.py   — ABC: get_releases(), get_releases_page_url()
-    gitea_provider.py     — Gitea REST API implementation
-    version_check.py      — normalize_version(), is_newer() using packaging.version
-    update_service.py     — Background asyncio task + state machine
-```
-
-**`ReleaseProvider` interface** — two methods:
-- `get_releases(limit) → list[ReleaseInfo]` — fetch releases (newest first)
-- `get_releases_page_url() → str` — link for "view on web"
-
-**`GiteaReleaseProvider`** calls `GET {base_url}/api/v1/repos/{repo}/releases`. Swapping to GitHub later means implementing the same interface against `api.github.com`.
-
-**Data models:**
-
-```python
-@dataclass(frozen=True)
-class AssetInfo:
-    name: str          # "LedGrab-v0.3.0-win-x64.zip"
-    size: int          # bytes
-    download_url: str
-
-@dataclass(frozen=True)
-class ReleaseInfo:
-    tag: str           # "v0.3.0"
-    version: str       # "0.3.0"
-    name: str          # "LedGrab v0.3.0"
-    body: str          # release notes markdown
-    prerelease: bool
-    published_at: str  # ISO 8601
-    assets: tuple[AssetInfo, ...]
-```
-
-### Version Comparison
-
-`version_check.py` — normalize Gitea tags to PEP 440:
-- `v0.3.0-alpha.1` → `0.3.0a1`
-- `v0.3.0-beta.2` → `0.3.0b2`
-- `v0.3.0-rc.3` → `0.3.0rc3`
-
-Uses `packaging.version.Version` for comparison.
-
-### Update Service
-
-Follows the **AutoBackupEngine pattern**:
-- Settings in `Database.get_setting("auto_update")`
-- asyncio.Task for periodic checks
-- 30s startup delay (avoid slowing boot)
-- 60s debounce on manual checks
-
-**State machine (Phase 1):** `IDLE → CHECKING → UPDATE_AVAILABLE`
-
-No download/apply in Phase 1 — just detection and notification.
-
-**Settings:** `enabled` (bool), `check_interval_hours` (float), `channel` ("stable" | "pre-release")
-
-**Persisted state:** `dismissed_version`, `last_check` (survives restarts)
-
-### API Endpoints
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| `GET` | `/api/v1/system/update/status` | Current state + available version |
-| `POST` | `/api/v1/system/update/check` | Trigger immediate check |
-| `POST` | `/api/v1/system/update/dismiss` | Dismiss notification for current version |
-| `GET` | `/api/v1/system/update/settings` | Get settings |
-| `PUT` | `/api/v1/system/update/settings` | Update settings |
-
-### Wiring
-
-- New `get_update_service()` in `dependencies.py`
-- `UpdateService` created in `main.py` lifespan, `start()`/`stop()` alongside other engines
-- Router registered in `api/__init__.py`
-- WebSocket event: `update_available` fired via `processor_manager.fire_event()`
-
-## Frontend
-
-### Version badge highlight
-
-The existing `#server-version` pill in the header gets a CSS class `has-update` when a newer version exists — changes the background to `var(--warning-color)` with a subtle pulse, making it clickable to open the update panel in settings.
-
-### Notification popup
-
-On `server:update_available` WebSocket event (and on page load if status says `has_update` and not dismissed):
-- A **persistent dismissible banner** slides in below the header (not the ephemeral 3s toast)
-- Shows: "Version {x.y.z} is available" + [View Release Notes] + [Dismiss]
-- Dismiss calls `POST /dismiss` and hides the bar for that version
-- Stored in `localStorage` so it doesn't re-show after page refresh for dismissed versions
-
-### Settings tab: "Updates"
-
-New 5th tab in the settings modal:
-- Current version display
-- "Check for updates" button + spinner
-- Channel selector (stable / pre-release) via IconSelect
-- Auto-check toggle + interval selector
-- When update available: release name, notes preview, link to releases page
-
-### i18n keys
-
-New `update.*` keys in `en.json`, `ru.json`, `zh.json` for all labels.
-
-## Files to Create
-
-| File | Purpose |
-|------|---------|
-| `core/update/__init__.py` | Package init |
-| `core/update/release_provider.py` | Abstract provider interface + data models |
-| `core/update/gitea_provider.py` | Gitea API implementation |
-| `core/update/version_check.py` | Semver normalization + comparison |
-| `core/update/update_service.py` | Background service + state machine |
-| `api/routes/update.py` | REST endpoints |
-| `api/schemas/update.py` | Pydantic request/response models |
-
-## Files to Modify
-
-| File | Change |
-|------|--------|
-| `api/__init__.py` | Register update router |
-| `api/dependencies.py` | Add `get_update_service()` |
-| `main.py` | Create & start/stop UpdateService in lifespan |
-| `templates/modals/settings.html` | Add Updates tab |
-| `static/js/features/settings.ts` | Update check/settings UI logic |
-| `static/js/core/api.ts` | Version badge highlight on health check |
-| `static/css/layout.css` | `.has-update` styles for version badge |
-| `static/locales/en.json` | i18n keys |
-| `static/locales/ru.json` | i18n keys |
-| `static/locales/zh.json` | i18n keys |
-
-## Future Phases (not in scope)
-
-- **Phase 2**: Download & stage artifacts
-- **Phase 3**: Apply update & restart (external updater script, NSIS silent mode)
-- **Phase 4**: Checksums, "What's new" dialog, update history

contexts/ci-cd.md

@@ -7,7 +7,8 @@
 | 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 |
+| `.gitea/workflows/release.yml` | Tag `v*` | Build Windows/Linux/Docker artifacts + create Gitea release |
+| `.gitea/workflows/build-android.yml` | Push master (android/server paths), tag `v*`, manual | Build Android APK; attach to release on tag |
 
 ## Release Pipeline (`release.yml`)
 
@@ -17,7 +18,7 @@ Four parallel jobs triggered by pushing a `v*` tag:
 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
+- Runs `build/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`)
@@ -25,7 +26,7 @@ Creates the Gitea release with a description table listing all artifacts. **The
 - Produces: **`LedGrab-{tag}-win-x64.zip`** (portable) and **`LedGrab-{tag}-setup.exe`** (NSIS installer)
 
 ### 3. `build-linux`
-- Runs `build-dist.sh` on Ubuntu
+- Runs `build/build-dist.sh` on Ubuntu
 - Creates a venv, installs deps, builds frontend
 - Produces: **`LedGrab-{tag}-linux-x64.tar.gz`**
 
@@ -38,8 +39,8 @@ Creates the Gitea release with a description table listing all artifacts. **The
 
 | Script | Platform | Output |
 |--------|----------|--------|
-| `build-dist-windows.sh` | Linux → Windows cross-build | ZIP + NSIS installer |
-| `build-dist.sh` | Linux native | tarball |
+| `build/build-dist-windows.sh` | Linux → Windows cross-build | ZIP + NSIS installer |
+| `build/build-dist.sh` | Linux native | tarball |
 | `server/Dockerfile` | Docker | Container image |
 
 ## Release Versioning
@@ -71,7 +72,7 @@ Build scripts use a fallback chain: CLI argument → exact git tag → CI env va
 - **Launch after install**: Use `MUI_FINISHPAGE_RUN_FUNCTION` (not `MUI_FINISHPAGE_RUN_PARAMETERS` — NSIS `Exec` chokes on quoting). Still requires `MUI_FINISHPAGE_RUN ""` defined for checkbox visibility
 - **Detect running instance**: `.onInit` checks file lock on `python.exe`, offers to kill process before install
 - **Uninstall preserves user data**: Remove `python/`, `app/`, `logs/` but NOT `data/`
-- **CI build**: `sudo apt-get install -y nsis msitools zip` then `makensis -DVERSION="${VERSION}" installer.nsi`
+- **CI build**: `sudo apt-get install -y nsis msitools zip` then `makensis -DVERSION="${VERSION}" build/installer.nsi`
 
 ## Hidden Launcher (VBS)
 
@@ -135,12 +136,12 @@ The `create-release` job has fallback logic — if the release already exists fo
 
 ```bash
 npm ci && npm run build                                              # frontend
-bash build-dist-windows.sh v1.0.0                                   # Windows dist
-"/c/Program Files (x86)/NSIS/makensis.exe" -DVERSION="1.0.0" installer.nsi  # installer
+bash build/build-dist-windows.sh v1.0.0                              # Windows dist
+"/c/Program Files (x86)/NSIS/makensis.exe" -DVERSION="1.0.0" build/installer.nsi  # installer
 ```
 
 ### Iterating on installer only
-If only `installer.nsi` changed (not app code), skip the full rebuild — just re-run `makensis`. If app code changed, re-run `build-dist-windows.sh` first since `dist/` is a snapshot.
+If only `installer.nsi` changed (not app code), skip the full rebuild — just re-run `makensis`. If app code changed, re-run `build/build-dist-windows.sh` first since `dist/` is a snapshot.
 
 ### Common issues
 

contexts/frontend.md

@@ -4,7 +4,7 @@
 
 ## CSS Custom Properties (Variables)
 
-Defined in `server/src/wled_controller/static/css/base.css`.
+Defined in `server/src/ledgrab/static/css/base.css`.
 
 **IMPORTANT:** There is NO `--accent` variable. Always use `--primary-color` for accent/brand color.
 
@@ -90,10 +90,26 @@ Plain `<select>` dropdowns should be enhanced with visual selectors depending on
 
 Both widgets hide the native `<select>` but keep it in the DOM with its value in sync. **The `<select>` and the visual widget are two separate things — changing one does NOT automatically update the other.** After programmatically changing the `<select>` value, call `.refresh()` (EntitySelect) or `.setValue(val)` (IconSelect) to update the trigger display. Call `.destroy()` when the modal closes.
 
+**CRITICAL pitfall — `<option>` elements required:** `IconSelect` does NOT create `<option>` elements in the native `<select>` — it only builds a visual popup grid. The native `<select>` must already contain matching `<option value="...">` elements (either from the Jinja2 template or added via JS) **before** `.value` is set. Setting `.value` on a `<select>` with no matching `<option>` **silently fails** — the value stays empty, and all downstream logic (section switching, auto-naming, type setup) breaks with no error. **When adding a new type to any IconSelect-enhanced `<select>`, you MUST add the `<option>` in the HTML template too.**
+
 **Common pitfall:** Using a preset/palette selector (e.g. gradient preset dropdown or effect type picker) that changes the underlying `<select>` value but forgets to call `.setValue()` on the IconSelect — the visual grid still shows the old selection.
 
 **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.
 
+### Dynamic entity lists (e.g. group child devices)
+
+When a modal needs an **ordered list of entity references** (like child devices in a group), use the `EntityPalette.pick()` pattern instead of plain `<select>` dropdowns per row. Each row should be a styled card with:
+
+- An icon (from `getDeviceTypeIcon()` / `getXxxIcon()`) showing the entity type
+- The entity name and metadata (LED count, type, etc.)
+- SVG icon buttons for reorder (chevron-up/down) and remove (trash)
+- A click handler that opens `EntityPalette.pick()` to change the selection
+- `data-*` attributes to store the selected value (not hidden `<select>` elements)
+
+See `_addGroupChildRow()` in `device-discovery.ts` for the reference implementation. This pattern keeps the list visually consistent with the rest of the UI and avoids plain HTML selects.
+
+For **mode/type toggles** with 2-4 fixed options (e.g. group mode: Sequence vs Independent), use `IconSelect` with descriptive icons and labels rather than radio buttons or plain selects. See `ensureGroupModeIconSelect()` for the pattern.
+
 ### 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.ts`:
@@ -175,7 +191,7 @@ When adding **new tabs, sections, or major UI elements**, update the correspondi
 
 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
+2. Copy the inner SVG elements (paths, circles, rects) into `icon-paths.ts` as a new export
 3. Add a corresponding `ICON_*` constant in `icons.ts` using `_svg(P.myIcon)`
 4. Import and use the constant in your feature module
 
@@ -213,7 +229,19 @@ Static HTML using `data-i18n` attributes is handled automatically by the i18n sy
 - `fetchWithAuth('/devices/dev_123', { method: 'DELETE' })` → `DELETE /api/v1/devices/dev_123`
 - Passing `/api/v1/gradients` results in **double prefix**: `/api/v1/api/v1/gradients` (404)
 
-For raw `fetch()` without auth (rare), use the full path manually.
+**NEVER use raw `fetch()` or `new Audio(url)` / `new Image()` for authenticated endpoints.** These bypass the auth token and will fail with 401. Always use `fetchWithAuth()` and convert to blob URLs when needed (e.g. for `<audio>`, `<img>`, or download links):
+
+```typescript
+// WRONG: no auth header — 401
+const audio = new Audio(`${API_BASE}/assets/${id}/file`);
+
+// CORRECT: fetch with auth, then create blob URL
+const res = await fetchWithAuth(`/assets/${id}/file`);
+const blob = await res.blob();
+const audio = new Audio(URL.createObjectURL(blob));
+```
+
+The only exception is raw `fetch()` for multipart uploads where you must set `Content-Type` to let the browser handle the boundary — but still use `getHeaders()` for the auth token.
 
 ## Bundling & Development Workflow
 
@@ -266,11 +294,11 @@ See [`contexts/chrome-tools.md`](chrome-tools.md) for Chrome MCP tool usage, bro
 
 ### Uptime / duration values
 
-Use `formatUptime(seconds)` from `core/ui.js`. Outputs `{s}s`, `{m}m {s}s`, or `{h}h {m}m` via i18n keys `time.seconds`, `time.minutes_seconds`, `time.hours_minutes`.
+Use `formatUptime(seconds)` from `core/ui.ts`. Outputs `{s}s`, `{m}m {s}s`, or `{h}h {m}m` via i18n keys `time.seconds`, `time.minutes_seconds`, `time.hours_minutes`.
 
 ### Large numbers
 
-Use `formatCompact(n)` from `core/ui.js`. Outputs `1.2K`, `3.5M` etc. Set `element.title` to the exact value for hover detail.
+Use `formatCompact(n)` from `core/ui.ts`. Outputs `1.2K`, `3.5M` etc. Set `element.title` to the exact value for hover detail.
 
 ### Preventing layout shift
 

contexts/server-operations.md

@@ -8,34 +8,38 @@ Two independent server modes with separate configs, ports, and data directories:
 
 | Mode | Command | Config | Port | API Key | Data |
 | ---- | ------- | ------ | ---- | ------- | ---- |
-| **Real** | `python -m wled_controller` | `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/` |
+| **Real** | `python -m ledgrab` | `config/default_config.yaml` | 8080 | `development-key-change-in-production` | `data/` |
+| **Demo** | `python -m ledgrab.demo` | `config/demo_config.yaml` | 8081 | `demo` | `data/demo/` |
 
-Both can run simultaneously on different ports.
+Demo mode can also be triggered via the `LEDGRAB_DEMO` environment variable (`true`, `1`, or `yes`). This works with any launch method — Python, Docker (`-e LEDGRAB_DEMO=true`), or the installed app (`set LEDGRAB_DEMO=true` before `LedGrab.bat`).
+
+Both modes can run simultaneously on different ports.
 
 ## Restart Procedure
 
+Use the PowerShell restart script — it gracefully shuts the running server down (so stores persist to disk), kills stragglers, launches a detached replacement, and polls the port until it's actually accepting connections. Exit code is 0 on success, 1 if the new server failed to bind the port, 2 on environment errors.
+
 ### 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"
+powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\led-grab-mixed\led-grab\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
+powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\led-grab-mixed\led-grab\server\restart.ps1" `
+    -Port 8081 -Module ledgrab.demo -ConfigPath "config\demo_config.yaml"
 ```
 
+### Useful parameters
+
+- `-Port <int>` / `-Module <name>` — override the target (default: 8080 / `ledgrab`).
+- `-StartupTimeoutSec <int>` — how long to wait for the new server to bind the port (default: 30).
+- `-ShutdownTimeoutSec <int>` — how long to wait for graceful shutdown before force-killing (default: 15).
+- `-Quiet` — suppress progress output.
+- `-SkipBrowser:$false` — allow the app to open a browser tab on startup (default: skipped).
+
 **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.
@@ -43,6 +47,7 @@ cd server && python -m wled_controller.demo
 ## When to Restart
 
 **Restart required** for changes to:
+
 - API routes (`api/routes/`, `api/schemas/`)
 - Core logic (`core/*.py`)
 - Configuration (`config.py`)
@@ -50,6 +55,7 @@ cd server && python -m wled_controller.demo
 - 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`)
@@ -66,13 +72,13 @@ Auto-reload is disabled (`reload=False` in `main.py`) due to watchfiles causing
 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.
+5. **New seed data**: Update `server/src/ledgrab/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()`
+- Config flag: `server/src/ledgrab/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`

custom_components/wled_screen_controller/__init__.py

@@ -1,208 +0,0 @@
-"""The LED Screen Controller integration."""
-from __future__ import annotations
-
-import logging
-from datetime import timedelta
-
-import voluptuous as vol
-
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import Platform
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers import device_registry as dr
-from homeassistant.helpers.aiohttp_client import async_get_clientsession
-
-from .const import (
-    DOMAIN,
-    CONF_SERVER_NAME,
-    CONF_SERVER_URL,
-    CONF_API_KEY,
-    DEFAULT_SCAN_INTERVAL,
-    TARGET_TYPE_KEY_COLORS,
-    DATA_COORDINATOR,
-    DATA_WS_MANAGER,
-    DATA_EVENT_LISTENER,
-)
-from .coordinator import WLEDScreenControllerCoordinator
-from .event_listener import EventStreamListener
-from .ws_manager import KeyColorsWebSocketManager
-
-_LOGGER = logging.getLogger(__name__)
-
-PLATFORMS: list[Platform] = [
-    Platform.BUTTON,
-    Platform.LIGHT,
-    Platform.SWITCH,
-    Platform.SENSOR,
-    Platform.NUMBER,
-    Platform.SELECT,
-]
-
-
-async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
-    """Set up LED Screen Controller from a config entry."""
-    server_name = entry.data.get(CONF_SERVER_NAME, "LED Screen Controller")
-    server_url = entry.data[CONF_SERVER_URL]
-    api_key = entry.data[CONF_API_KEY]
-
-    session = async_get_clientsession(hass)
-    coordinator = WLEDScreenControllerCoordinator(
-        hass,
-        session,
-        server_url,
-        api_key,
-        update_interval=timedelta(seconds=DEFAULT_SCAN_INTERVAL),
-    )
-
-    await coordinator.async_config_entry_first_refresh()
-
-    ws_manager = KeyColorsWebSocketManager(hass, server_url, api_key)
-
-    event_listener = EventStreamListener(hass, server_url, api_key, coordinator)
-    await event_listener.start()
-
-    # Create device entries for each target and remove stale ones
-    device_registry = dr.async_get(hass)
-    current_identifiers: set[tuple[str, str]] = set()
-    if coordinator.data and "targets" in coordinator.data:
-        for target_id, target_data in coordinator.data["targets"].items():
-            info = target_data["info"]
-            target_type = info.get("target_type", "led")
-            model = (
-                "Key Colors Target"
-                if target_type == TARGET_TYPE_KEY_COLORS
-                else "LED Target"
-            )
-            device_registry.async_get_or_create(
-                config_entry_id=entry.entry_id,
-                identifiers={(DOMAIN, target_id)},
-                name=info.get("name", target_id),
-                manufacturer=server_name,
-                model=model,
-                configuration_url=server_url,
-            )
-            current_identifiers.add((DOMAIN, target_id))
-
-    # Create a single "Scenes" device for scene preset buttons
-    scenes_identifier = (DOMAIN, f"{entry.entry_id}_scenes")
-    scene_presets = coordinator.data.get("scene_presets", []) if coordinator.data else []
-    if scene_presets:
-        device_registry.async_get_or_create(
-            config_entry_id=entry.entry_id,
-            identifiers={scenes_identifier},
-            name="Scenes",
-            manufacturer=server_name,
-            model="Scene Presets",
-            configuration_url=server_url,
-        )
-        current_identifiers.add(scenes_identifier)
-
-    # Remove devices for targets that no longer exist
-    for device_entry in dr.async_entries_for_config_entry(
-        device_registry, entry.entry_id
-    ):
-        if not device_entry.identifiers & current_identifiers:
-            _LOGGER.info("Removing stale device: %s", device_entry.name)
-            device_registry.async_remove_device(device_entry.id)
-
-    # Store data
-    hass.data.setdefault(DOMAIN, {})
-    hass.data[DOMAIN][entry.entry_id] = {
-        DATA_COORDINATOR: coordinator,
-        DATA_WS_MANAGER: ws_manager,
-        DATA_EVENT_LISTENER: event_listener,
-    }
-
-    # Track target and scene IDs to detect changes
-    known_target_ids = set(
-        coordinator.data.get("targets", {}).keys() if coordinator.data else []
-    )
-    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
-
-        targets = coordinator.data.get("targets", {})
-
-        # Start/stop WS connections for KC targets based on processing state
-        for target_id, target_data in targets.items():
-            info = target_data.get("info", {})
-            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
-        current_ids = set(targets.keys())
-        current_scene_ids = set(
-            p["id"] for p in coordinator.data.get("scene_presets", [])
-        )
-        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)
-            )
-
-    coordinator.async_add_listener(_on_coordinator_update)
-
-    # Register set_leds service (once across all entries)
-    async def handle_set_leds(call) -> None:
-        """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 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)
-                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(
-            DOMAIN,
-            "set_leds",
-            handle_set_leds,
-            schema=vol.Schema({
-                vol.Required("source_id"): str,
-                vol.Required("segments"): list,
-            }),
-        )
-
-    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
-
-    return True
-
-
-async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
-    """Unload a config entry."""
-    entry_data = hass.data[DOMAIN][entry.entry_id]
-    await entry_data[DATA_WS_MANAGER].shutdown()
-    await entry_data[DATA_EVENT_LISTENER].shutdown()
-
-    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
-
-    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

custom_components/wled_screen_controller/button.py

@@ -1,74 +0,0 @@
-"""Button platform for LED Screen Controller — scene preset activation."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from homeassistant.components.button import ButtonEntity
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import DOMAIN, DATA_COORDINATOR
-from .coordinator import WLEDScreenControllerCoordinator
-
-_LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up scene preset buttons."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-
-    entities = []
-    if coordinator.data:
-        for preset in coordinator.data.get("scene_presets", []):
-            entities.append(
-                SceneActivateButton(coordinator, preset, entry.entry_id)
-            )
-
-    async_add_entities(entities)
-
-
-class SceneActivateButton(CoordinatorEntity, ButtonEntity):
-    """Button that activates a scene preset."""
-
-    _attr_has_entity_name = True
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        preset: dict[str, Any],
-        entry_id: str,
-    ) -> None:
-        """Initialize the button."""
-        super().__init__(coordinator)
-        self._preset_id = preset["id"]
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{entry_id}_scene_{preset['id']}"
-        self._attr_translation_key = "activate_scene"
-        self._attr_translation_placeholders = {"scene_name": preset["name"]}
-        self._attr_icon = "mdi:palette"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information — all scene buttons belong to the Scenes device."""
-        return {"identifiers": {(DOMAIN, f"{self._entry_id}_scenes")}}
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        if not self.coordinator.data:
-            return False
-        return self._preset_id in {
-            p["id"] for p in self.coordinator.data.get("scene_presets", [])
-        }
-
-    async def async_press(self) -> None:
-        """Activate the scene preset."""
-        await self.coordinator.activate_scene(self._preset_id)

custom_components/wled_screen_controller/config_flow.py

@@ -1,127 +0,0 @@
-"""Config flow for LED Screen Controller integration."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-from urllib.parse import urlparse, urlunparse
-
-import aiohttp
-import voluptuous as vol
-
-from homeassistant import config_entries
-from homeassistant.core import HomeAssistant
-from homeassistant.data_entry_flow import FlowResult
-from homeassistant.helpers.aiohttp_client import async_get_clientsession
-
-from .const import DOMAIN, CONF_SERVER_NAME, CONF_SERVER_URL, CONF_API_KEY, DEFAULT_TIMEOUT
-
-_LOGGER = logging.getLogger(__name__)
-
-STEP_USER_DATA_SCHEMA = vol.Schema(
-    {
-        vol.Optional(CONF_SERVER_NAME, default="LED Screen Controller"): str,
-        vol.Required(CONF_SERVER_URL, default="http://localhost:8080"): str,
-        vol.Optional(CONF_API_KEY, default=""): str,
-    }
-)
-
-
-def normalize_url(url: str) -> str:
-    """Normalize URL to ensure port is an integer."""
-    parsed = urlparse(url)
-
-    if parsed.port is not None:
-        netloc = parsed.hostname or "localhost"
-        port = int(parsed.port)
-        if port != (443 if parsed.scheme == "https" else 80):
-            netloc = f"{netloc}:{port}"
-        parsed = parsed._replace(netloc=netloc)
-
-    return urlunparse(parsed)
-
-
-async def validate_server(
-    hass: HomeAssistant, server_url: str, api_key: str
-) -> dict[str, Any]:
-    """Validate server connectivity and API key."""
-    session = async_get_clientsession(hass)
-    timeout = aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT)
-
-    # Step 1: Check connectivity via health endpoint (no auth needed)
-    try:
-        async with session.get(f"{server_url}/health", timeout=timeout) as resp:
-            if resp.status != 200:
-                raise ConnectionError(f"Server returned status {resp.status}")
-            data = await resp.json()
-            version = data.get("version", "unknown")
-    except aiohttp.ClientError as err:
-        raise ConnectionError(f"Cannot connect to server: {err}") from err
-
-    # Step 2: Validate API key via authenticated endpoint (skip if no key and auth not required)
-    auth_required = data.get("auth_required", True)
-    if api_key:
-        headers = {"Authorization": f"Bearer {api_key}"}
-        try:
-            async with session.get(
-                f"{server_url}/api/v1/output-targets",
-                headers=headers,
-                timeout=timeout,
-            ) as resp:
-                if resp.status == 401:
-                    raise PermissionError("Invalid API key")
-                resp.raise_for_status()
-        except PermissionError:
-            raise
-        except aiohttp.ClientError as err:
-            raise ConnectionError(f"API request failed: {err}") from err
-    elif auth_required:
-        raise PermissionError("Server requires an API key")
-
-    return {"version": version}
-
-
-class WLEDScreenControllerConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
-    """Handle a config flow for LED Screen Controller."""
-
-    VERSION = 2
-
-    async def async_step_user(
-        self, user_input: dict[str, Any] | None = None
-    ) -> FlowResult:
-        """Handle the initial step."""
-        errors: dict[str, str] = {}
-
-        if user_input is not None:
-            server_name = user_input.get(CONF_SERVER_NAME, "LED Screen Controller")
-            server_url = normalize_url(user_input[CONF_SERVER_URL].rstrip("/"))
-            api_key = user_input[CONF_API_KEY]
-
-            try:
-                await validate_server(self.hass, server_url, api_key)
-
-                await self.async_set_unique_id(server_url)
-                self._abort_if_unique_id_configured()
-
-                return self.async_create_entry(
-                    title=server_name,
-                    data={
-                        CONF_SERVER_NAME: server_name,
-                        CONF_SERVER_URL: server_url,
-                        CONF_API_KEY: api_key,
-                    },
-                )
-
-            except ConnectionError as err:
-                _LOGGER.error("Connection error: %s", err)
-                errors["base"] = "cannot_connect"
-            except PermissionError:
-                errors["base"] = "invalid_api_key"
-            except Exception as err:
-                _LOGGER.exception("Unexpected exception: %s", err)
-                errors["base"] = "unknown"
-
-        return self.async_show_form(
-            step_id="user",
-            data_schema=STEP_USER_DATA_SCHEMA,
-            errors=errors,
-        )

custom_components/wled_screen_controller/const.py

@@ -1,23 +0,0 @@
-"""Constants for the LED Screen Controller integration."""
-
-DOMAIN = "wled_screen_controller"
-
-# Configuration
-CONF_SERVER_NAME = "server_name"
-CONF_SERVER_URL = "server_url"
-CONF_API_KEY = "api_key"
-
-# Default values
-DEFAULT_SCAN_INTERVAL = 3  # seconds
-DEFAULT_TIMEOUT = 10  # seconds
-WS_RECONNECT_DELAY = 5  # seconds
-WS_MAX_RECONNECT_DELAY = 60  # seconds
-
-# Target types
-TARGET_TYPE_LED = "led"
-TARGET_TYPE_KEY_COLORS = "key_colors"
-
-# Data keys stored in hass.data[DOMAIN][entry_id]
-DATA_COORDINATOR = "coordinator"
-DATA_WS_MANAGER = "ws_manager"
-DATA_EVENT_LISTENER = "event_listener"

custom_components/wled_screen_controller/coordinator.py

@@ -1,459 +0,0 @@
-"""Data update coordinator for LED Screen Controller."""
-from __future__ import annotations
-
-import asyncio
-from datetime import timedelta
-import logging
-from typing import Any
-
-import aiohttp
-
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
-
-from .const import (
-    DOMAIN,
-    DEFAULT_TIMEOUT,
-    TARGET_TYPE_KEY_COLORS,
-)
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class WLEDScreenControllerCoordinator(DataUpdateCoordinator):
-    """Class to manage fetching LED Screen Controller data."""
-
-    def __init__(
-        self,
-        hass: HomeAssistant,
-        session: aiohttp.ClientSession,
-        server_url: str,
-        api_key: str,
-        update_interval: timedelta,
-    ) -> None:
-        """Initialize the coordinator."""
-        self.server_url = server_url
-        self.session = session
-        self.api_key = api_key
-        self.server_version = "unknown"
-        self._auth_headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
-        self._timeout = aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT)
-
-        super().__init__(
-            hass,
-            _LOGGER,
-            name=DOMAIN,
-            update_interval=update_interval,
-        )
-
-    async def _async_update_data(self) -> dict[str, Any]:
-        """Fetch data from API."""
-        try:
-            async with asyncio.timeout(DEFAULT_TIMEOUT * 3):
-                if self.server_version == "unknown":
-                    await self._fetch_server_version()
-
-                targets_list = await self._fetch_targets()
-
-                # Fetch state and metrics for all targets in parallel
-                targets_data: dict[str, dict[str, Any]] = {}
-
-                async def fetch_target_data(target: dict) -> tuple[str, dict]:
-                    target_id = target["id"]
-                    try:
-                        state, metrics = await asyncio.gather(
-                            self._fetch_target_state(target_id),
-                            self._fetch_target_metrics(target_id),
-                        )
-                    except Exception as err:
-                        _LOGGER.warning(
-                            "Failed to fetch data for target %s: %s",
-                            target_id,
-                            err,
-                        )
-                        state = None
-                        metrics = None
-
-                    result: dict[str, Any] = {
-                        "info": target,
-                        "state": state,
-                        "metrics": metrics,
-                    }
-
-                    # Fetch rectangles for key_colors targets
-                    if target.get("target_type") == TARGET_TYPE_KEY_COLORS:
-                        kc_settings = target.get("key_colors_settings") or {}
-                        template_id = kc_settings.get("pattern_template_id", "")
-                        if template_id:
-                            result["rectangles"] = await self._fetch_rectangles(
-                                template_id
-                            )
-                        else:
-                            result["rectangles"] = []
-                    else:
-                        result["rectangles"] = []
-
-                    return target_id, result
-
-                results = await asyncio.gather(
-                    *(fetch_target_data(t) for t in targets_list),
-                    return_exceptions=True,
-                )
-
-                for r in results:
-                    if isinstance(r, Exception):
-                        _LOGGER.warning("Target fetch failed: %s", r)
-                        continue
-                    target_id, data = r
-                    targets_data[target_id] = data
-
-                # Fetch devices, CSS sources, value sources, and scene presets in parallel
-                devices_data, css_sources, value_sources, scene_presets = (
-                    await asyncio.gather(
-                        self._fetch_devices(),
-                        self._fetch_css_sources(),
-                        self._fetch_value_sources(),
-                        self._fetch_scene_presets(),
-                    )
-                )
-
-                return {
-                    "targets": targets_data,
-                    "devices": devices_data,
-                    "css_sources": css_sources,
-                    "value_sources": value_sources,
-                    "scene_presets": scene_presets,
-                    "server_version": self.server_version,
-                }
-
-        except asyncio.TimeoutError as err:
-            raise UpdateFailed(f"Timeout fetching data: {err}") from err
-        except aiohttp.ClientError as err:
-            raise UpdateFailed(f"Error communicating with API: {err}") from err
-
-    async def _fetch_server_version(self) -> None:
-        """Fetch server version from health endpoint."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/health",
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                self.server_version = data.get("version", "unknown")
-        except Exception as err:
-            _LOGGER.warning("Failed to fetch server version: %s", err)
-            self.server_version = "unknown"
-
-    async def _fetch_targets(self) -> list[dict[str, Any]]:
-        """Fetch all output targets."""
-        async with self.session.get(
-            f"{self.server_url}/api/v1/output-targets",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            resp.raise_for_status()
-            data = await resp.json()
-            return data.get("targets", [])
-
-    async def _fetch_target_state(self, target_id: str) -> dict[str, Any]:
-        """Fetch target processing state."""
-        async with self.session.get(
-            f"{self.server_url}/api/v1/output-targets/{target_id}/state",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            resp.raise_for_status()
-            return await resp.json()
-
-    async def _fetch_target_metrics(self, target_id: str) -> dict[str, Any]:
-        """Fetch target metrics."""
-        async with self.session.get(
-            f"{self.server_url}/api/v1/output-targets/{target_id}/metrics",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            resp.raise_for_status()
-            return await resp.json()
-
-    async def _fetch_rectangles(self, template_id: str) -> list[dict]:
-        """Fetch rectangles for a pattern template (no cache — always fresh)."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/api/v1/pattern-templates/{template_id}",
-                headers=self._auth_headers,
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                return data.get("rectangles", [])
-        except Exception as err:
-            _LOGGER.warning(
-                "Failed to fetch pattern template %s: %s", template_id, err
-            )
-            return []
-
-    async def _fetch_devices(self) -> dict[str, dict[str, Any]]:
-        """Fetch all devices with capabilities and brightness."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/api/v1/devices",
-                headers=self._auth_headers,
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                devices = data.get("devices", [])
-        except Exception as err:
-            _LOGGER.warning("Failed to fetch devices: %s", err)
-            return {}
-
-        # Fetch brightness for all capable devices in parallel
-        async def fetch_device_entry(device: dict) -> tuple[str, dict[str, Any]]:
-            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=self._timeout,
-                    ) as resp:
-                        if resp.status == 200:
-                            bri_data = await resp.json()
-                            entry["brightness"] = bri_data.get("brightness")
-                except Exception as err:
-                    _LOGGER.warning(
-                        "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
-
-    async def set_brightness(self, device_id: str, brightness: int) -> None:
-        """Set brightness for a device."""
-        async with self.session.put(
-            f"{self.server_url}/api/v1/devices/{device_id}/brightness",
-            headers={**self._auth_headers, "Content-Type": "application/json"},
-            json={"brightness": brightness},
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to set brightness for device %s: %s %s",
-                    device_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def set_color(self, device_id: str, color: list[int] | None) -> None:
-        """Set or clear the static color for a device."""
-        async with self.session.put(
-            f"{self.server_url}/api/v1/devices/{device_id}/color",
-            headers={**self._auth_headers, "Content-Type": "application/json"},
-            json={"color": color},
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to set color for device %s: %s %s",
-                    device_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def set_kc_brightness(self, target_id: str, brightness: int) -> None:
-        """Set brightness for a Key Colors target (0-255 mapped to 0.0-1.0)."""
-        brightness_float = round(brightness / 255, 4)
-        async with self.session.put(
-            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=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to set KC brightness for target %s: %s %s",
-                    target_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def _fetch_css_sources(self) -> list[dict[str, Any]]:
-        """Fetch all color strip sources."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/api/v1/color-strip-sources",
-                headers=self._auth_headers,
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                return data.get("sources", [])
-        except Exception as err:
-            _LOGGER.warning("Failed to fetch CSS sources: %s", err)
-            return []
-
-    async def _fetch_value_sources(self) -> list[dict[str, Any]]:
-        """Fetch all value sources."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/api/v1/value-sources",
-                headers=self._auth_headers,
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                return data.get("sources", [])
-        except Exception as err:
-            _LOGGER.warning("Failed to fetch value sources: %s", err)
-            return []
-
-    async def _fetch_scene_presets(self) -> list[dict[str, Any]]:
-        """Fetch all scene presets."""
-        try:
-            async with self.session.get(
-                f"{self.server_url}/api/v1/scene-presets",
-                headers=self._auth_headers,
-                timeout=self._timeout,
-            ) as resp:
-                resp.raise_for_status()
-                data = await resp.json()
-                return data.get("presets", [])
-        except Exception as err:
-            _LOGGER.warning("Failed to fetch scene presets: %s", err)
-            return []
-
-    async def push_colors(self, source_id: str, colors: list[list[int]]) -> None:
-        """Push flat color array to an api_input CSS source."""
-        async with self.session.post(
-            f"{self.server_url}/api/v1/color-strip-sources/{source_id}/colors",
-            headers={**self._auth_headers, "Content-Type": "application/json"},
-            json={"colors": colors},
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status not in (200, 204):
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to push colors to source %s: %s %s",
-                    source_id, resp.status, body,
-                )
-                resp.raise_for_status()
-
-    async def push_segments(self, source_id: str, segments: list[dict]) -> None:
-        """Push segment data to an api_input CSS source."""
-        async with self.session.post(
-            f"{self.server_url}/api/v1/color-strip-sources/{source_id}/colors",
-            headers={**self._auth_headers, "Content-Type": "application/json"},
-            json={"segments": segments},
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status not in (200, 204):
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to push segments to source %s: %s %s",
-                    source_id, resp.status, body,
-                )
-                resp.raise_for_status()
-
-    async def activate_scene(self, preset_id: str) -> None:
-        """Activate a scene preset."""
-        async with self.session.post(
-            f"{self.server_url}/api/v1/scene-presets/{preset_id}/activate",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to activate scene %s: %s %s",
-                    preset_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def update_source(self, source_id: str, **kwargs: Any) -> None:
-        """Update a color strip source's fields."""
-        async with self.session.put(
-            f"{self.server_url}/api/v1/color-strip-sources/{source_id}",
-            headers={**self._auth_headers, "Content-Type": "application/json"},
-            json=kwargs,
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "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 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=self._timeout,
-        ) as resp:
-            if resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to update target %s: %s %s",
-                    target_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def start_processing(self, target_id: str) -> None:
-        """Start processing for a target."""
-        async with self.session.post(
-            f"{self.server_url}/api/v1/output-targets/{target_id}/start",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status == 409:
-                _LOGGER.debug("Target %s already processing", target_id)
-            elif resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to start target %s: %s %s",
-                    target_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()
-
-    async def stop_processing(self, target_id: str) -> None:
-        """Stop processing for a target."""
-        async with self.session.post(
-            f"{self.server_url}/api/v1/output-targets/{target_id}/stop",
-            headers=self._auth_headers,
-            timeout=self._timeout,
-        ) as resp:
-            if resp.status == 409:
-                _LOGGER.debug("Target %s already stopped", target_id)
-            elif resp.status != 200:
-                body = await resp.text()
-                _LOGGER.error(
-                    "Failed to stop target %s: %s %s",
-                    target_id, resp.status, body,
-                )
-                resp.raise_for_status()
-        await self.async_request_refresh()

custom_components/wled_screen_controller/event_listener.py

@@ -1,95 +0,0 @@
-"""WebSocket event listener for server state change notifications."""
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import json
-import logging
-
-import aiohttp
-
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.aiohttp_client import async_get_clientsession
-from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
-
-from .const import WS_RECONNECT_DELAY, WS_MAX_RECONNECT_DELAY
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class EventStreamListener:
-    """Listens to server WS endpoint for state change events.
-
-    Triggers a coordinator refresh whenever a target starts or stops processing,
-    so HAOS entities react near-instantly to external state changes.
-    """
-
-    def __init__(
-        self,
-        hass: HomeAssistant,
-        server_url: str,
-        api_key: str,
-        coordinator: DataUpdateCoordinator,
-    ) -> None:
-        self._hass = hass
-        self._server_url = server_url
-        self._api_key = api_key
-        self._coordinator = coordinator
-        self._task: asyncio.Task | None = None
-        self._shutting_down = False
-
-    async def start(self) -> None:
-        """Start listening to the event stream."""
-        self._task = self._hass.async_create_background_task(
-            self._ws_loop(),
-            "wled_screen_controller_events",
-        )
-
-    async def _ws_loop(self) -> None:
-        """WebSocket connection loop with reconnection."""
-        delay = WS_RECONNECT_DELAY
-        session = async_get_clientsession(self._hass)
-        ws_base = self._server_url.replace("http://", "ws://").replace(
-            "https://", "wss://"
-        )
-        url = f"{ws_base}/api/v1/events/ws?token={self._api_key}"
-
-        while not self._shutting_down:
-            try:
-                async with session.ws_connect(url) as ws:
-                    delay = WS_RECONNECT_DELAY  # reset on successful connect
-                    _LOGGER.debug("Event stream connected")
-                    async for msg in ws:
-                        if msg.type == aiohttp.WSMsgType.TEXT:
-                            try:
-                                data = json.loads(msg.data)
-                            except json.JSONDecodeError:
-                                continue
-                            if data.get("type") == "state_change":
-                                await self._coordinator.async_request_refresh()
-                        elif msg.type in (
-                            aiohttp.WSMsgType.CLOSED,
-                            aiohttp.WSMsgType.ERROR,
-                        ):
-                            break
-            except asyncio.CancelledError:
-                raise
-            except (aiohttp.ClientError, asyncio.TimeoutError, OSError) as err:
-                _LOGGER.debug("Event stream connection error: %s", err)
-            except Exception as err:
-                _LOGGER.error("Unexpected event stream error: %s", err)
-
-            if self._shutting_down:
-                break
-
-            await asyncio.sleep(delay)
-            delay = min(delay * 2, WS_MAX_RECONNECT_DELAY)
-
-    async def shutdown(self) -> None:
-        """Stop listening."""
-        self._shutting_down = True
-        if self._task:
-            self._task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await self._task
-            self._task = None

custom_components/wled_screen_controller/light.py

@@ -1,151 +0,0 @@
-"""Light platform for LED Screen Controller (api_input CSS sources)."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from homeassistant.components.light import (
-    ATTR_BRIGHTNESS,
-    ATTR_RGB_COLOR,
-    ColorMode,
-    LightEntity,
-)
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import DOMAIN, DATA_COORDINATOR
-from .coordinator import WLEDScreenControllerCoordinator
-
-_LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up LED Screen Controller api_input lights."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-
-    entities = []
-    if coordinator.data:
-        for source in coordinator.data.get("css_sources", []):
-            if source.get("source_type") == "api_input":
-                entities.append(
-                    ApiInputLight(coordinator, source, entry.entry_id)
-                )
-
-    async_add_entities(entities)
-
-
-class ApiInputLight(CoordinatorEntity, LightEntity):
-    """Representation of an api_input CSS source as a light entity."""
-
-    _attr_has_entity_name = True
-    _attr_color_mode = ColorMode.RGB
-    _attr_supported_color_modes = {ColorMode.RGB}
-    _attr_translation_key = "api_input_light"
-    _attr_icon = "mdi:led-strip-variant"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        source: dict[str, Any],
-        entry_id: str,
-    ) -> None:
-        """Initialize the light."""
-        super().__init__(coordinator)
-        self._source_id: str = source["id"]
-        self._source_name: str = source.get("name", self._source_id)
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{self._source_id}_light"
-
-        # Restore state from fallback_color
-        fallback = self._get_fallback_color()
-        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
-    def device_info(self) -> dict[str, Any]:
-        """Return device information — one virtual device per api_input source."""
-        return {
-            "identifiers": {(DOMAIN, self._source_id)},
-            "name": self._source_name,
-            "manufacturer": "WLED Screen Controller",
-            "model": "API Input CSS Source",
-        }
-
-    @property
-    def name(self) -> str:
-        """Return the entity name."""
-        return self._source_name
-
-    @property
-    def is_on(self) -> bool:
-        """Return true if the light is on."""
-        return self._is_on
-
-    @property
-    def rgb_color(self) -> tuple[int, int, int]:
-        """Return the current RGB color."""
-        return self._rgb_color
-
-    @property
-    def brightness(self) -> int:
-        """Return the current brightness (0-255)."""
-        return self._brightness
-
-    async def async_turn_on(self, **kwargs: Any) -> None:
-        """Turn on the light, optionally setting color and brightness."""
-        if ATTR_RGB_COLOR in kwargs:
-            self._rgb_color = kwargs[ATTR_RGB_COLOR]
-        if ATTR_BRIGHTNESS in kwargs:
-            self._brightness = kwargs[ATTR_BRIGHTNESS]
-
-        # Scale RGB by brightness
-        scale = self._brightness / 255
-        r, g, b = self._rgb_color
-        scaled = [round(r * scale), round(g * scale), round(b * scale)]
-
-        await self.coordinator.push_segments(
-            self._source_id,
-            [{"start": 0, "length": 9999, "mode": "solid", "color": scaled}],
-        )
-        # Update fallback_color so the color persists beyond the timeout
-        await self.coordinator.update_source(
-            self._source_id, fallback_color=scaled,
-        )
-        self._is_on = True
-        self.async_write_ha_state()
-
-    async def async_turn_off(self, **kwargs: Any) -> None:
-        """Turn off the light by pushing black and setting fallback to black."""
-        off_color = [0, 0, 0]
-        await self.coordinator.push_segments(
-            self._source_id,
-            [{"start": 0, "length": 9999, "mode": "solid", "color": off_color}],
-        )
-        await self.coordinator.update_source(
-            self._source_id, fallback_color=off_color,
-        )
-        self._is_on = False
-        self.async_write_ha_state()
-
-    def _get_fallback_color(self) -> list[int]:
-        """Read fallback_color from the source config in coordinator data."""
-        if not self.coordinator.data:
-            return [0, 0, 0]
-        for source in self.coordinator.data.get("css_sources", []):
-            if source.get("id") == self._source_id:
-                fallback = source.get("fallback_color")
-                if fallback and len(fallback) >= 3:
-                    return list(fallback[:3])
-                break
-        return [0, 0, 0]

custom_components/wled_screen_controller/manifest.json

@@ -1,12 +0,0 @@
-{
-  "domain": "wled_screen_controller",
-  "name": "LED Screen Controller",
-  "codeowners": ["@alexeidolgolyov"],
-  "config_flow": true,
-  "dependencies": [],
-  "documentation": "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed",
-  "iot_class": "local_push",
-  "issue_tracker": "https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues",
-  "requirements": ["aiohttp>=3.9.0"],
-  "version": "0.2.0"
-}

custom_components/wled_screen_controller/number.py

@@ -1,169 +0,0 @@
-"""Number platform for LED Screen Controller (device & KC target brightness)."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from homeassistant.components.number import NumberEntity, NumberMode
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import DOMAIN, DATA_COORDINATOR, TARGET_TYPE_KEY_COLORS
-from .coordinator import WLEDScreenControllerCoordinator
-
-_LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up LED Screen Controller brightness numbers."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-
-    entities = []
-    if coordinator.data and "targets" in coordinator.data:
-        devices = coordinator.data.get("devices") or {}
-
-        for target_id, target_data in coordinator.data["targets"].items():
-            info = target_data["info"]
-
-            if info.get("target_type") == TARGET_TYPE_KEY_COLORS:
-                # KC target — brightness lives in key_colors_settings
-                entities.append(
-                    WLEDScreenControllerKCBrightness(
-                        coordinator, target_id, entry.entry_id,
-                    )
-                )
-                continue
-
-            # LED target — brightness lives on the device
-            device_id = info.get("device_id", "")
-            if not device_id:
-                continue
-
-            device_data = devices.get(device_id)
-            if not device_data:
-                continue
-
-            capabilities = device_data.get("info", {}).get("capabilities") or []
-            if "brightness_control" not in capabilities or "static_color" in capabilities:
-                continue
-
-            entities.append(
-                WLEDScreenControllerBrightness(
-                    coordinator, target_id, device_id, entry.entry_id,
-                )
-            )
-
-    async_add_entities(entities)
-
-
-class WLEDScreenControllerBrightness(CoordinatorEntity, NumberEntity):
-    """Brightness control for an LED device associated with a target."""
-
-    _attr_has_entity_name = True
-    _attr_native_min_value = 0
-    _attr_native_max_value = 255
-    _attr_native_step = 1
-    _attr_mode = NumberMode.SLIDER
-    _attr_icon = "mdi:brightness-6"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        device_id: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the brightness number."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._device_id = device_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_brightness"
-        self._attr_translation_key = "brightness"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def native_value(self) -> float | None:
-        """Return the current brightness value."""
-        if not self.coordinator.data:
-            return None
-        device_data = self.coordinator.data.get("devices", {}).get(self._device_id)
-        if not device_data:
-            return None
-        return device_data.get("brightness")
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        if not self.coordinator.data:
-            return False
-        targets = self.coordinator.data.get("targets", {})
-        devices = self.coordinator.data.get("devices", {})
-        return self._target_id in targets and self._device_id in devices
-
-    async def async_set_native_value(self, value: float) -> None:
-        """Set brightness value."""
-        await self.coordinator.set_brightness(self._device_id, int(value))
-
-
-class WLEDScreenControllerKCBrightness(CoordinatorEntity, NumberEntity):
-    """Brightness control for a Key Colors target."""
-
-    _attr_has_entity_name = True
-    _attr_native_min_value = 0
-    _attr_native_max_value = 255
-    _attr_native_step = 1
-    _attr_mode = NumberMode.SLIDER
-    _attr_icon = "mdi:brightness-6"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the KC brightness number."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_brightness"
-        self._attr_translation_key = "brightness"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def native_value(self) -> float | None:
-        """Return the current brightness value (0-255)."""
-        if not self.coordinator.data:
-            return None
-        target_data = self.coordinator.data.get("targets", {}).get(self._target_id)
-        if not target_data:
-            return None
-        kc_settings = target_data.get("info", {}).get("key_colors_settings") or {}
-        brightness_float = kc_settings.get("brightness", 1.0)
-        return round(brightness_float * 255)
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        if not self.coordinator.data:
-            return False
-        return self._target_id in self.coordinator.data.get("targets", {})
-
-    async def async_set_native_value(self, value: float) -> None:
-        """Set brightness value."""
-        await self.coordinator.set_kc_brightness(self._target_id, int(value))

custom_components/wled_screen_controller/select.py

@@ -1,177 +0,0 @@
-"""Select platform for LED Screen Controller (CSS source & brightness source)."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from homeassistant.components.select import SelectEntity
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import DOMAIN, DATA_COORDINATOR, TARGET_TYPE_KEY_COLORS
-from .coordinator import WLEDScreenControllerCoordinator
-
-_LOGGER = logging.getLogger(__name__)
-
-NONE_OPTION = "— None —"
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up LED Screen Controller select entities."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-
-    entities: list[SelectEntity] = []
-    if coordinator.data and "targets" in coordinator.data:
-        for target_id, target_data in coordinator.data["targets"].items():
-            info = target_data["info"]
-
-            # Only LED targets
-            if info.get("target_type") == TARGET_TYPE_KEY_COLORS:
-                continue
-
-            entities.append(
-                CSSSourceSelect(coordinator, target_id, entry.entry_id)
-            )
-            entities.append(
-                BrightnessSourceSelect(coordinator, target_id, entry.entry_id)
-            )
-
-    async_add_entities(entities)
-
-
-class CSSSourceSelect(CoordinatorEntity, SelectEntity):
-    """Select entity for choosing a color strip source for an LED target."""
-
-    _attr_has_entity_name = True
-    _attr_icon = "mdi:palette"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_css_source"
-        self._attr_translation_key = "color_strip_source"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def options(self) -> list[str]:
-        if not self.coordinator.data:
-            return []
-        sources = self.coordinator.data.get("css_sources") or []
-        return [s["name"] for s in sources]
-
-    @property
-    def current_option(self) -> str | None:
-        if not self.coordinator.data:
-            return None
-        target_data = self.coordinator.data.get("targets", {}).get(self._target_id)
-        if not target_data:
-            return None
-        current_id = target_data["info"].get("color_strip_source_id", "")
-        sources = self.coordinator.data.get("css_sources") or []
-        for s in sources:
-            if s["id"] == current_id:
-                return s["name"]
-        return None
-
-    @property
-    def available(self) -> bool:
-        if not self.coordinator.data:
-            return False
-        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_map().get(option)
-        if source_id is None:
-            _LOGGER.error("CSS source not found: %s", option)
-            return
-        await self.coordinator.update_target(
-            self._target_id, color_strip_source_id=source_id
-        )
-
-    def _name_to_id_map(self) -> dict[str, str]:
-        sources = (self.coordinator.data or {}).get("css_sources") or []
-        return {s["name"]: s["id"] for s in sources}
-
-
-class BrightnessSourceSelect(CoordinatorEntity, SelectEntity):
-    """Select entity for choosing a brightness value source for an LED target."""
-
-    _attr_has_entity_name = True
-    _attr_icon = "mdi:brightness-auto"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_brightness_source"
-        self._attr_translation_key = "brightness_source"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def options(self) -> list[str]:
-        if not self.coordinator.data:
-            return [NONE_OPTION]
-        sources = self.coordinator.data.get("value_sources") or []
-        return [NONE_OPTION] + [s["name"] for s in sources]
-
-    @property
-    def current_option(self) -> str | None:
-        if not self.coordinator.data:
-            return None
-        target_data = self.coordinator.data.get("targets", {}).get(self._target_id)
-        if not target_data:
-            return None
-        current_id = target_data["info"].get("brightness_value_source_id", "")
-        if not current_id:
-            return NONE_OPTION
-        sources = self.coordinator.data.get("value_sources") or []
-        for s in sources:
-            if s["id"] == current_id:
-                return s["name"]
-        return NONE_OPTION
-
-    @property
-    def available(self) -> bool:
-        if not self.coordinator.data:
-            return False
-        return self._target_id in self.coordinator.data.get("targets", {})
-
-    async def async_select_option(self, option: str) -> None:
-        if option == NONE_OPTION:
-            source_id = ""
-        else:
-            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
-        )

custom_components/wled_screen_controller/sensor.py

@@ -1,273 +0,0 @@
-"""Sensor platform for LED Screen Controller."""
-from __future__ import annotations
-
-import logging
-from collections.abc import Callable
-from typing import Any
-
-from homeassistant.components.sensor import (
-    SensorDeviceClass,
-    SensorEntity,
-    SensorStateClass,
-)
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import (
-    DOMAIN,
-    TARGET_TYPE_KEY_COLORS,
-    DATA_COORDINATOR,
-    DATA_WS_MANAGER,
-)
-from .coordinator import WLEDScreenControllerCoordinator
-from .ws_manager import KeyColorsWebSocketManager
-
-_LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up LED Screen Controller sensors."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-    ws_manager: KeyColorsWebSocketManager = data[DATA_WS_MANAGER]
-
-    entities: list[SensorEntity] = []
-    if coordinator.data and "targets" in coordinator.data:
-        for target_id, target_data in coordinator.data["targets"].items():
-            entities.append(
-                WLEDScreenControllerFPSSensor(coordinator, target_id, entry.entry_id)
-            )
-            entities.append(
-                WLEDScreenControllerStatusSensor(
-                    coordinator, target_id, entry.entry_id
-                )
-            )
-
-            # Add color sensors for Key Colors targets
-            info = target_data["info"]
-            if info.get("target_type") == TARGET_TYPE_KEY_COLORS:
-                rectangles = target_data.get("rectangles", [])
-                for rect in rectangles:
-                    entities.append(
-                        WLEDScreenControllerColorSensor(
-                            coordinator=coordinator,
-                            ws_manager=ws_manager,
-                            target_id=target_id,
-                            rectangle_name=rect["name"],
-                            entry_id=entry.entry_id,
-                        )
-                    )
-
-    async_add_entities(entities)
-
-
-class WLEDScreenControllerFPSSensor(CoordinatorEntity, SensorEntity):
-    """FPS sensor for a LED Screen Controller target."""
-
-    _attr_has_entity_name = True
-    _attr_state_class = SensorStateClass.MEASUREMENT
-    _attr_native_unit_of_measurement = "FPS"
-    _attr_icon = "mdi:speedometer"
-    _attr_suggested_display_precision = 1
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the sensor."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_fps"
-        self._attr_translation_key = "fps"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def native_value(self) -> float | None:
-        """Return the FPS value."""
-        target_data = self._get_target_data()
-        if not target_data or not target_data.get("state"):
-            return None
-        state = target_data["state"]
-        if not state.get("processing"):
-            return None
-        return state.get("fps_actual")
-
-    @property
-    def extra_state_attributes(self) -> dict[str, Any]:
-        """Return additional attributes."""
-        target_data = self._get_target_data()
-        if not target_data or not target_data.get("state"):
-            return {}
-        return {"fps_target": target_data["state"].get("fps_target")}
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        return self._get_target_data() is not None
-
-    def _get_target_data(self) -> dict[str, Any] | None:
-        if not self.coordinator.data:
-            return None
-        return self.coordinator.data.get("targets", {}).get(self._target_id)
-
-
-class WLEDScreenControllerStatusSensor(CoordinatorEntity, SensorEntity):
-    """Status sensor for a LED Screen Controller target."""
-
-    _attr_has_entity_name = True
-    _attr_icon = "mdi:information-outline"
-    _attr_device_class = SensorDeviceClass.ENUM
-    _attr_options = ["processing", "idle", "error", "unavailable"]
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the sensor."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_status"
-        self._attr_translation_key = "status"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def native_value(self) -> str:
-        """Return the status."""
-        target_data = self._get_target_data()
-        if not target_data:
-            return "unavailable"
-        state = target_data.get("state")
-        if not state:
-            return "unavailable"
-        if state.get("processing"):
-            errors = state.get("errors", [])
-            if errors:
-                return "error"
-            return "processing"
-        return "idle"
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        return self._get_target_data() is not None
-
-    def _get_target_data(self) -> dict[str, Any] | None:
-        if not self.coordinator.data:
-            return None
-        return self.coordinator.data.get("targets", {}).get(self._target_id)
-
-
-class WLEDScreenControllerColorSensor(CoordinatorEntity, SensorEntity):
-    """Color sensor reporting the extracted screen color for a Key Colors rectangle."""
-
-    _attr_has_entity_name = True
-    _attr_icon = "mdi:palette"
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        ws_manager: KeyColorsWebSocketManager,
-        target_id: str,
-        rectangle_name: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the color sensor."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._rectangle_name = rectangle_name
-        self._ws_manager = ws_manager
-        self._entry_id = entry_id
-        self._unregister_ws: Callable[[], None] | None = None
-
-        sanitized = rectangle_name.lower().replace(" ", "_").replace("-", "_")
-        self._attr_unique_id = f"{target_id}_{sanitized}_color"
-        self._attr_translation_key = "rectangle_color"
-        self._attr_translation_placeholders = {"rectangle_name": rectangle_name}
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    async def async_added_to_hass(self) -> None:
-        """Register WS callback when entity is added."""
-        await super().async_added_to_hass()
-        self._unregister_ws = self._ws_manager.register_callback(
-            self._target_id, self._handle_color_update
-        )
-
-    async def async_will_remove_from_hass(self) -> None:
-        """Unregister WS callback when entity is removed."""
-        if self._unregister_ws:
-            self._unregister_ws()
-            self._unregister_ws = None
-        await super().async_will_remove_from_hass()
-
-    def _handle_color_update(self, colors: dict) -> None:
-        """Handle incoming color update from WebSocket."""
-        if self._rectangle_name in colors:
-            self.async_write_ha_state()
-
-    @property
-    def native_value(self) -> str | None:
-        """Return the hex color string (e.g. #FF8800)."""
-        color = self._get_color()
-        if color is None:
-            return None
-        return f"#{color['r']:02X}{color['g']:02X}{color['b']:02X}"
-
-    @property
-    def extra_state_attributes(self) -> dict[str, Any]:
-        """Return r, g, b, brightness as attributes."""
-        color = self._get_color()
-        if color is None:
-            return {}
-        r, g, b = color["r"], color["g"], color["b"]
-        brightness = int(0.299 * r + 0.587 * g + 0.114 * b)
-        return {
-            "r": r,
-            "g": g,
-            "b": b,
-            "brightness": brightness,
-            "rgb_color": [r, g, b],
-        }
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        return self._get_target_data() is not None
-
-    def _get_color(self) -> dict[str, int] | None:
-        """Get the current color for this rectangle from WS manager."""
-        target_data = self._get_target_data()
-        if not target_data or not target_data.get("state"):
-            return None
-        if not target_data["state"].get("processing"):
-            return None
-        colors = self._ws_manager.get_latest_colors(self._target_id)
-        return colors.get(self._rectangle_name)
-
-    def _get_target_data(self) -> dict[str, Any] | None:
-        if not self.coordinator.data:
-            return None
-        return self.coordinator.data.get("targets", {}).get(self._target_id)

custom_components/wled_screen_controller/services.yaml

@@ -1,19 +0,0 @@
-set_leds:
-  name: Set LEDs
-  description: Push segment data to an api_input color strip source
-  fields:
-    source_id:
-      name: Source ID
-      description: The api_input CSS source ID (e.g., css_abc12345)
-      required: true
-      selector:
-        text:
-    segments:
-      name: Segments
-      description: >
-        List of segment objects. Each segment has: start (int), length (int),
-        mode ("solid"/"per_pixel"/"gradient"), color ([R,G,B] for solid),
-        colors ([[R,G,B],...] for per_pixel/gradient)
-      required: true
-      selector:
-        object:

custom_components/wled_screen_controller/strings.json

@@ -1,91 +0,0 @@
-{
-  "config": {
-    "step": {
-      "user": {
-        "title": "Set up LED Screen Controller",
-        "description": "Enter the URL and API key for your LED Screen Controller server.",
-        "data": {
-          "server_name": "Server Name",
-          "server_url": "Server URL",
-          "api_key": "API Key"
-        },
-        "data_description": {
-          "server_name": "Display name for this server in Home Assistant",
-          "server_url": "URL of your LED Screen Controller server (e.g., http://192.168.1.100:8080)",
-          "api_key": "API key from your server's configuration file"
-        }
-      }
-    },
-    "error": {
-      "cannot_connect": "Failed to connect to server.",
-      "invalid_api_key": "Invalid API key.",
-      "unknown": "Unexpected error occurred."
-    },
-    "abort": {
-      "already_configured": "This server is already configured."
-    }
-  },
-  "entity": {
-    "button": {
-      "activate_scene": {
-        "name": "{scene_name}"
-      }
-    },
-    "light": {
-      "api_input_light": {
-        "name": "Light"
-      }
-    },
-    "switch": {
-      "processing": {
-        "name": "Processing"
-      }
-    },
-    "sensor": {
-      "fps": {
-        "name": "FPS"
-      },
-      "status": {
-        "name": "Status",
-        "state": {
-          "processing": "Processing",
-          "idle": "Idle",
-          "error": "Error",
-          "unavailable": "Unavailable"
-        }
-      },
-      "rectangle_color": {
-        "name": "{rectangle_name} Color"
-      }
-    },
-    "number": {
-      "brightness": {
-        "name": "Brightness"
-      }
-    },
-    "select": {
-      "color_strip_source": {
-        "name": "Color Strip Source"
-      },
-      "brightness_source": {
-        "name": "Brightness Source"
-      }
-    }
-  },
-  "services": {
-    "set_leds": {
-      "name": "Set LEDs",
-      "description": "Push segment data to an api_input color strip source.",
-      "fields": {
-        "source_id": {
-          "name": "Source ID",
-          "description": "The api_input CSS source ID (e.g., css_abc12345)."
-        },
-        "segments": {
-          "name": "Segments",
-          "description": "List of segment objects with start, length, mode, and color/colors fields."
-        }
-      }
-    }
-  }
-}

custom_components/wled_screen_controller/switch.py

@@ -1,109 +0,0 @@
-"""Switch platform for LED Screen Controller."""
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from homeassistant.components.switch import SwitchEntity
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from homeassistant.helpers.update_coordinator import CoordinatorEntity
-
-from .const import DOMAIN, DATA_COORDINATOR
-from .coordinator import WLEDScreenControllerCoordinator
-
-_LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: ConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up LED Screen Controller switches."""
-    data = hass.data[DOMAIN][entry.entry_id]
-    coordinator: WLEDScreenControllerCoordinator = data[DATA_COORDINATOR]
-
-    entities = []
-    if coordinator.data and "targets" in coordinator.data:
-        for target_id, target_data in coordinator.data["targets"].items():
-            entities.append(
-                WLEDScreenControllerSwitch(coordinator, target_id, entry.entry_id)
-            )
-
-    async_add_entities(entities)
-
-
-class WLEDScreenControllerSwitch(CoordinatorEntity, SwitchEntity):
-    """Representation of a LED Screen Controller target processing switch."""
-
-    _attr_has_entity_name = True
-
-    def __init__(
-        self,
-        coordinator: WLEDScreenControllerCoordinator,
-        target_id: str,
-        entry_id: str,
-    ) -> None:
-        """Initialize the switch."""
-        super().__init__(coordinator)
-        self._target_id = target_id
-        self._entry_id = entry_id
-        self._attr_unique_id = f"{target_id}_processing"
-        self._attr_translation_key = "processing"
-        self._attr_icon = "mdi:television-ambient-light"
-
-    @property
-    def device_info(self) -> dict[str, Any]:
-        """Return device information."""
-        return {"identifiers": {(DOMAIN, self._target_id)}}
-
-    @property
-    def is_on(self) -> bool:
-        """Return true if processing is active."""
-        target_data = self._get_target_data()
-        if not target_data or not target_data.get("state"):
-            return False
-        return target_data["state"].get("processing", False)
-
-    @property
-    def available(self) -> bool:
-        """Return if entity is available."""
-        return self._get_target_data() is not None
-
-    @property
-    def extra_state_attributes(self) -> dict[str, Any]:
-        """Return additional state attributes."""
-        target_data = self._get_target_data()
-        if not target_data:
-            return {}
-
-        attrs: dict[str, Any] = {"target_id": self._target_id}
-        state = target_data.get("state") or {}
-        metrics = target_data.get("metrics") or {}
-
-        if state:
-            attrs["fps_target"] = state.get("fps_target")
-            attrs["fps_actual"] = state.get("fps_actual")
-
-        if metrics:
-            attrs["frames_processed"] = metrics.get("frames_processed")
-            attrs["errors_count"] = metrics.get("errors_count")
-            attrs["uptime_seconds"] = metrics.get("uptime_seconds")
-
-        return attrs
-
-    async def async_turn_on(self, **kwargs: Any) -> None:
-        """Start processing."""
-        await self.coordinator.start_processing(self._target_id)
-
-    async def async_turn_off(self, **kwargs: Any) -> None:
-        """Stop processing."""
-        await self.coordinator.stop_processing(self._target_id)
-
-    def _get_target_data(self) -> dict[str, Any] | None:
-        """Get target data from coordinator."""
-        if not self.coordinator.data:
-            return None
-        return self.coordinator.data.get("targets", {}).get(self._target_id)

custom_components/wled_screen_controller/translations/en.json

@@ -1,75 +0,0 @@
-{
-  "config": {
-    "step": {
-      "user": {
-        "title": "Set up LED Screen Controller",
-        "description": "Enter the URL and API key for your LED Screen Controller server.",
-        "data": {
-          "server_name": "Server Name",
-          "server_url": "Server URL",
-          "api_key": "API Key"
-        },
-        "data_description": {
-          "server_name": "Display name for this server in Home Assistant",
-          "server_url": "URL of your LED Screen Controller server (e.g., http://192.168.1.100:8080)",
-          "api_key": "API key from your server's configuration file"
-        }
-      }
-    },
-    "error": {
-      "cannot_connect": "Failed to connect to server.",
-      "invalid_api_key": "Invalid API key.",
-      "unknown": "Unexpected error occurred."
-    },
-    "abort": {
-      "already_configured": "This server is already configured."
-    }
-  },
-  "entity": {
-    "button": {
-      "activate_scene": {
-        "name": "{scene_name}"
-      }
-    },
-    "light": {
-      "api_input_light": {
-        "name": "Light"
-      }
-    },
-    "switch": {
-      "processing": {
-        "name": "Processing"
-      }
-    },
-    "sensor": {
-      "fps": {
-        "name": "FPS"
-      },
-      "status": {
-        "name": "Status",
-        "state": {
-          "processing": "Processing",
-          "idle": "Idle",
-          "error": "Error",
-          "unavailable": "Unavailable"
-        }
-      },
-      "rectangle_color": {
-        "name": "{rectangle_name} Color"
-      }
-    },
-    "number": {
-      "brightness": {
-        "name": "Brightness"
-      }
-    },
-    "select": {
-      "color_strip_source": {
-        "name": "Color Strip Source"
-      },
-      "brightness_source": {
-        "name": "Brightness Source"
-      }
-    }
-  }
-}

custom_components/wled_screen_controller/translations/ru.json

@@ -1,75 +0,0 @@
-{
-  "config": {
-    "step": {
-      "user": {
-        "title": "Настройка LED Screen Controller",
-        "description": "Введите URL и API-ключ вашего сервера LED Screen Controller.",
-        "data": {
-          "server_name": "Имя сервера",
-          "server_url": "URL сервера",
-          "api_key": "API-ключ"
-        },
-        "data_description": {
-          "server_name": "Отображаемое имя сервера в Home Assistant",
-          "server_url": "URL сервера LED Screen Controller (например, http://192.168.1.100:8080)",
-          "api_key": "API-ключ из конфигурационного файла сервера"
-        }
-      }
-    },
-    "error": {
-      "cannot_connect": "Не удалось подключиться к серверу.",
-      "invalid_api_key": "Неверный API-ключ.",
-      "unknown": "Произошла непредвиденная ошибка."
-    },
-    "abort": {
-      "already_configured": "Этот сервер уже настроен."
-    }
-  },
-  "entity": {
-    "button": {
-      "activate_scene": {
-        "name": "{scene_name}"
-      }
-    },
-    "light": {
-      "api_input_light": {
-        "name": "Подсветка"
-      }
-    },
-    "switch": {
-      "processing": {
-        "name": "Обработка"
-      }
-    },
-    "sensor": {
-      "fps": {
-        "name": "FPS"
-      },
-      "status": {
-        "name": "Статус",
-        "state": {
-          "processing": "Обработка",
-          "idle": "Ожидание",
-          "error": "Ошибка",
-          "unavailable": "Недоступен"
-        }
-      },
-      "rectangle_color": {
-        "name": "{rectangle_name} Цвет"
-      }
-    },
-    "number": {
-      "brightness": {
-        "name": "Яркость"
-      }
-    },
-    "select": {
-      "color_strip_source": {
-        "name": "Источник цветовой полосы"
-      },
-      "brightness_source": {
-        "name": "Источник яркости"
-      }
-    }
-  }
-}

custom_components/wled_screen_controller/ws_manager.py

@@ -1,136 +0,0 @@
-"""WebSocket connection manager for Key Colors target color streams."""
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import json
-import logging
-from collections.abc import Callable
-from typing import Any
-
-import aiohttp
-
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.aiohttp_client import async_get_clientsession
-
-from .const import WS_RECONNECT_DELAY, WS_MAX_RECONNECT_DELAY
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class KeyColorsWebSocketManager:
-    """Manages WebSocket connections for Key Colors target color streams."""
-
-    def __init__(
-        self,
-        hass: HomeAssistant,
-        server_url: str,
-        api_key: str,
-    ) -> None:
-        self._hass = hass
-        self._server_url = server_url
-        self._api_key = api_key
-        self._connections: dict[str, asyncio.Task] = {}
-        self._callbacks: dict[str, list[Callable]] = {}
-        self._latest_colors: dict[str, dict[str, dict[str, int]]] = {}
-        self._shutting_down = False
-
-    def _get_ws_url(self, target_id: str) -> str:
-        """Build WebSocket URL for a target."""
-        ws_base = self._server_url.replace("http://", "ws://").replace(
-            "https://", "wss://"
-        )
-        return f"{ws_base}/api/v1/output-targets/{target_id}/ws?token={self._api_key}"
-
-    async def start_listening(self, target_id: str) -> None:
-        """Start WebSocket connection for a target."""
-        if target_id in self._connections:
-            return
-        task = self._hass.async_create_background_task(
-            self._ws_loop(target_id),
-            f"wled_screen_controller_ws_{target_id}",
-        )
-        self._connections[target_id] = task
-
-    async def stop_listening(self, target_id: str) -> None:
-        """Stop WebSocket connection for a target."""
-        task = self._connections.pop(target_id, None)
-        if task:
-            task.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await task
-        self._latest_colors.pop(target_id, None)
-
-    def register_callback(
-        self, target_id: str, callback: Callable
-    ) -> Callable[[], None]:
-        """Register a callback for color updates. Returns unregister function."""
-        self._callbacks.setdefault(target_id, []).append(callback)
-
-        def unregister() -> None:
-            cbs = self._callbacks.get(target_id)
-            if cbs and callback in cbs:
-                cbs.remove(callback)
-
-        return unregister
-
-    def get_latest_colors(self, target_id: str) -> dict[str, dict[str, int]]:
-        """Get latest colors for a target."""
-        return self._latest_colors.get(target_id, {})
-
-    async def _ws_loop(self, target_id: str) -> None:
-        """WebSocket connection loop with reconnection."""
-        delay = WS_RECONNECT_DELAY
-        session = async_get_clientsession(self._hass)
-
-        while not self._shutting_down:
-            try:
-                url = self._get_ws_url(target_id)
-                async with session.ws_connect(url) as ws:
-                    delay = WS_RECONNECT_DELAY  # reset on successful connect
-                    _LOGGER.debug("WS connected for target %s", target_id)
-                    async for msg in ws:
-                        if msg.type == aiohttp.WSMsgType.TEXT:
-                            self._handle_message(target_id, msg.data)
-                        elif msg.type in (
-                            aiohttp.WSMsgType.CLOSED,
-                            aiohttp.WSMsgType.ERROR,
-                        ):
-                            break
-            except asyncio.CancelledError:
-                raise
-            except (aiohttp.ClientError, asyncio.TimeoutError, OSError) as err:
-                _LOGGER.debug("WS connection error for %s: %s", target_id, err)
-            except Exception as err:
-                _LOGGER.error("Unexpected WS error for %s: %s", target_id, err)
-
-            if self._shutting_down:
-                break
-
-            await asyncio.sleep(delay)
-            delay = min(delay * 2, WS_MAX_RECONNECT_DELAY)
-
-    def _handle_message(self, target_id: str, raw: str) -> None:
-        """Handle incoming WebSocket message."""
-        try:
-            data = json.loads(raw)
-        except json.JSONDecodeError:
-            return
-
-        if data.get("type") != "colors_update":
-            return
-
-        colors: dict[str, Any] = data.get("colors", {})
-        self._latest_colors[target_id] = colors
-
-        for cb in self._callbacks.get(target_id, []):
-            try:
-                cb(colors)
-            except Exception:
-                _LOGGER.exception("Error in WS color callback for %s", target_id)
-
-    async def shutdown(self) -> None:
-        """Stop all WebSocket connections."""
-        self._shutting_down = True
-        for target_id in list(self._connections):
-            await self.stop_listening(target_id)

docs/API.md

@@ -1,6 +1,6 @@
-# WLED Screen Controller API Documentation
+# LedGrab API Documentation
 
-Complete REST API reference for the WLED Screen Controller server.
+Complete REST API reference for the LedGrab server.
 
 **Base URL:** `http://localhost:8080`
 **API Version:** v1

docs/BLE_LED_CONTROLLERS.md

@@ -0,0 +1,109 @@
+# BLE LED Controllers — Investigation & Implementation Notes
+
+Reference for anyone touching the BLE device provider (`server/src/ledgrab/core/devices/ble_*`). Captures the protocol quirks, Windows/bleak traps, and hardware lockdown we hit while bringing up SP110E / Triones / Zengge / Govee support.
+
+## Architecture
+
+```
+BLEDeviceProvider  →  BLEClient  →  BLETransport (desktop: bleak, Android: Kotlin BleBridge via Chaquopy)
+                           │
+                           └─ BLEProtocol (family-specific wire bytes: sp110e.py, triones.py, zengge.py, govee.py)
+```
+
+- One `BLEProtocol` dataclass per controller family. Each supplies GATT UUIDs, write type (with/without response), `encode_color` / `encode_power` functions, name prefixes for discovery, and an optional `init_writes` handshake sequence.
+- `BLEClient` is whole-strip only. `send_pixels()` averages incoming pixel arrays and emits one solid color per frame — none of these protocols support per-pixel streaming.
+- Discovery auto-detects the family via advertised name prefix first, falls back to service UUID matching. The detected family is returned on `DiscoveredDevice.ble_family` and preselected in the UI.
+- The settings modal lets users change the family after creation — wrong family → writes go to a characteristic the device ignores → strip stays dark.
+
+## Protocol Quirks
+
+### SP110E / SP108E (critical handshake)
+
+The controller **silently tears the GATT link down within ~1 second of connect** unless a two-write handshake arrives immediately:
+
+```
+Write  01 00                      → characteristic FFE2
+Write  01 B7 E3 D5                → characteristic FFE1
+```
+
+Without this, the first real write later hangs for 30 s because bleak thinks the link is up but the peripheral has already dropped it. We carry these writes in `PROTOCOL.init_writes` and execute them from `BLEClient.connect()` right after GATT open.
+
+Color frame is **4 bytes** (`RR GG BB 1E`), not 5 — the earlier implementation had a stray `0x00` padding byte that the device tolerated but isn't documented.
+
+Source: [mbullington's reverse-engineering gist](https://gist.github.com/mbullington/37957501a07ad065b67d4e8d39bfe012).
+
+### Triones / Zengge / Govee
+
+No init handshake required. Color frames and command bytes documented inline in each protocol module. Notable: Zengge and SP110E share service UUID `FFE0/FFE1`, so name-based identification is the only reliable way to tell them apart. In `_register_builtins()`, SP110E is registered first so it wins the `identify_family_by_service_uuids` tie by default — change this if the user base flips.
+
+## bleak + Windows WinRT Traps
+
+These bit us hard. All are now worked around, but future BLE work should keep them in mind.
+
+### 1. `asyncio.wait_for` hangs forever on WinRT
+
+`BleakClient.connect()` / `write_gatt_char()` wrap WinRT `IAsyncOperation`s. When asyncio tries to cancel them (as `wait_for` does on timeout), the WinRT task **never finishes cancelling**, so `wait_for` itself blocks forever while awaiting the cancellation. Symptom: log stops with no timeout error, process is alive but wedged.
+
+**Fix**: `_bounded_await()` in [ble_transport.py](../server/src/ledgrab/core/devices/ble_transport.py) uses `asyncio.wait()` instead, which returns on timeout without awaiting pending tasks. Orphans the hanging WinRT task but frees the caller.
+
+### 2. Connect by raw MAC string fails on Windows
+
+Passing `BleakClient("AA:BB:CC:DD:EE:FF")` makes WinRT guess the address type (public vs random static vs random resolvable). Guesses wrong → connect silently times out. Symptom: `TimeoutError: BLE connect to ... exceeded 10.0s` with no other signal.
+
+**Fix**: Always pre-scan with `BleakScanner.find_device_by_address()` and pass the returned `BLEDevice` object to `BleakClient`. Costs ~400 ms but makes connect reliable.
+
+### 3. Client-side fetch timeout too short for BLE target start
+
+The target-start endpoint does a ~5 s pre-scan + up to 10 s GATT connect + init handshake. Default `fetchWithAuth` has a 10 s timeout and 3× retry, so the UI was aborting and retrying concurrent `/start` requests into the server.
+
+**Fix**: `startTargetProcessing` overrides `timeout: 30000, retry: false`.
+
+### 4. `Start-Process -WindowStyle Hidden` from bash/WSL strips handles
+
+When `restart.ps1` is invoked from Git-Bash / WSL, `Start-Process` inherited handles cause the child uvicorn to exit immediately. Stream redirection fixes it.
+
+**Fix**: `restart.ps1` always uses `-RedirectStandardOutput`/`-RedirectStandardError` to a temp log. Failed startups dump the stderr tail to the caller so root cause is visible.
+
+## Vendor Lockdown (the dead end)
+
+Some controllers — notably the one we tested, advertising as `AlexTable` at `16:61:05:70:68:44` — **only accept connections from the vendor phone app**. Diagnostic sequence:
+
+| Test | Result | Meaning |
+| --- | --- | --- |
+| LedGrab `BleakClient.connect()` | 10 s timeout | Windows can't connect |
+| Windows "Bluetooth LE Explorer" | Hangs on connect | Same Windows stack as bleak — not our bug |
+| Phone **OS** Bluetooth Settings | Can't connect | Phone OS uses generic BLE stack — also fails |
+| Phone **LED Hue** app | Connects fine | Vendor app is the *only* working client |
+
+At this point, further Windows/bleak tweaks have no effect. The peripheral firmware rejects generic GATT connects and only stays connected when the LED Hue app emits its vendor-specific handshake. To unlock such a controller from LedGrab you'd need to:
+
+1. Enable **Developer Options → Bluetooth HCI snoop log** on Android.
+2. Reproduce the LED Hue flow (connect → color change → disconnect).
+3. `adb bugreport bugreport.zip`; extract `btsnoop_hci.log`.
+4. Open in Wireshark; identify the vendor handshake bytes written during connect.
+5. Add them to the protocol's `init_writes`.
+
+Alternatively, replace the BLE controller hardware with **WLED on ESP32** — $3, fully supported, vastly more capable.
+
+## Frontend
+
+- BLE family picker uses the project's shared `IconSelect` grid (project rule — see [CLAUDE.md](../CLAUDE.md): "NEVER use plain HTML `<select>`").
+- Registry in `device-discovery.ts` is keyed by element ID so both the add-device and settings modals get their own IconSelect instance. Helpers: `ensureBleFamilyIconSelect(selectId, onChange?)` / `destroyBleFamilyIconSelect(selectId)`.
+- Govee AES key row is conditionally visible: only shows when the selected family is `govee`.
+
+## HAOS Integration Pair
+
+The sister repo `ledgrab-haos-integration` had its own WebSocket auth bug that surfaced during this session — the integration still used the deprecated `?token=<key>` query param instead of the new first-message handshake. Fixed in [v0.2.1](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration). Unrelated to BLE but shared debugging time.
+
+## Tests
+
+`server/tests/test_ble_protocols.py` and `server/tests/test_ble_client.py` use a `FakeTransport` that logs every write with its `char_uuid`, so protocol wire formats and the init handshake are unit-testable without hardware or bleak installed. New protocol additions should extend these.
+
+## Files
+
+- [ble_client.py](../server/src/ledgrab/core/devices/ble_client.py) — provider-facing class; runs init handshake on connect; reconnect backoff.
+- [ble_transport.py](../server/src/ledgrab/core/devices/ble_transport.py) — bleak desktop transport; `_bounded_await` helper; per-write char override.
+- [android_ble_transport.py](../server/src/ledgrab/core/devices/android_ble_transport.py) — Chaquopy/Kotlin transport; currently ignores `char_uuid` override (bridge binds a single write characteristic).
+- [ble_provider.py](../server/src/ledgrab/core/devices/ble_provider.py) — discovery, family detection, `set_color` / `set_power` short-lived sessions.
+- [ble_protocols/](../server/src/ledgrab/core/devices/ble_protocols/) — one file per family (pure byte-encoding functions, no BLE deps).
+- [BleBridge.kt](../android/app/src/main/java/com/ledgrab/android/BleBridge.kt) — Android-side BLE GATT wrapper exposed to Python via Chaquopy.

hacs.json

@@ -1,6 +0,0 @@
-{
-  "name": "WLED Screen Controller",
-  "render_readme": true,
-  "country": ["US"],
-  "homeassistant": "2023.1.0"
-}

plans/demo-mode/CONTEXT.md

@@ -1,30 +0,0 @@
-# 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

plans/demo-mode/PLAN.md

@@ -1,44 +0,0 @@
-# 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`

plans/demo-mode/phase-1-config-flag.md

@@ -1,42 +0,0 @@
-# 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 -->