feat(targets): automatic brightness limiting (ABL) / per-LED power budget

Cap an addressable strip's estimated current draw to a PSU budget so bright/
white scenes can't brown out an under-spec'd supply (voltage sag -> red/orange
shift, flicker, controller resets) — a classic 'it's broken' first impression.

- New core/processing/power_limit.py: pure current estimate (full white over N
  LEDs draws N * mA_per_led) + a (0,1] scale to land a frame on budget.
- Applied in WledTargetProcessor._send_to_device (single choke point, every send
  path; scales into a reusable scratch buffer, never mutates shared frames).
- Two per-target fields on LED targets: max_milliamps (0 = unlimited) and
  milliamps_per_led (default 55), threaded through model/store/manager/processor/
  schema/route with hot-update via update_target_settings. Additive with safe
  defaults (no data migration needed; legacy targets read as unlimited).
- Frontend: editor fields + i18n (en/ru/zh) + LedOutputTarget type.
- Tests: 10 unit tests for the estimator/scale; full suite green (1911 passed).

.gitea/workflows/release.yml

@@ -98,6 +98,9 @@ jobs:
           print(json.dumps('\n\n'.join(sections)))
           ")
 
+          # Created as draft so the release isn't user-visible until every
+          # build job has attached its assets. The publish-release job at
+          # the end of the workflow flips draft=false once all builds pass.
           RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
             -H "Authorization: token $GITEA_TOKEN" \
             -H "Content-Type: application/json" \
@@ -105,7 +108,7 @@ jobs:
               \"tag_name\": \"$TAG\",
               \"name\": \"LedGrab $TAG\",
               \"body\": $BODY_JSON,
-              \"draft\": false,
+              \"draft\": true,
               \"prerelease\": $IS_PRE
             }")
 
@@ -350,3 +353,25 @@ jobs:
           if ! echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
             docker push "$REGISTRY:latest"
           fi
+
+  # ── Publish the release (flip draft=false) ─────────────────
+  # Runs only after every build job succeeded so users never see a
+  # release that's missing artifacts or sha256 sidecars (the in-app
+  # updater refuses to install without them).
+  publish-release:
+    needs: [create-release, build-windows, build-linux, build-docker]
+    if: github.event_name == 'push' && success()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Promote draft release to published
+        env:
+          GITEA_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          RELEASE_ID="${{ needs.create-release.outputs.release_id }}"
+          BASE_URL="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+
+          curl -s -X PATCH "$BASE_URL/releases/$RELEASE_ID" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d '{"draft": false}'
+          echo "Published release $RELEASE_ID"

README.md

@@ -1,36 +1,58 @@
 # LED Grab
 
-Ambient lighting system that captures screen content and drives LED strips in real time. Supports WLED, Adalight, AmbileD, and DDP devices with audio-reactive effects, pattern generation, and automated profile switching.
+Ambient lighting system that captures screen content and drives LED strips and smart lights in real time. Supports a wide range of devices — WLED, DDP, Adalight, smart bulbs, PC peripherals, Bluetooth strips, and more — with audio-reactive effects, pattern generation, and condition-based automation.
+
+**Free and open source.** LedGrab is released under the [MIT license](LICENSE) — free to use, modify, and self-host, with no accounts, telemetry, or cloud dependency. Everything runs locally on your own machine and network.
 
 ## What It Does
 
-The server captures pixels from a screen (or Android device via ADB), extracts border colors, applies post-processing filters, and streams the result to LED strips at up to 60 fps. A built-in web dashboard provides device management, calibration, live LED preview, and real-time metrics — no external UI required.
+The server captures pixels from a screen (or from a connected Android phone via ADB), extracts border colors, applies a post-processing filter pipeline, and streams the result to your LED devices at up to 60 fps. A built-in web dashboard provides device management, calibration, a visual wiring editor, live LED preview, and real-time metrics — no external UI required.
 
-A Home Assistant integration exposes devices as entities for smart home automation.
+A separate Home Assistant integration exposes devices as entities for smart-home automation.
+
+## Screenshots
+
+![LedGrab dashboard](docs/screenshots/dashboard.PNG)
+
+*Dashboard — live system performance, integrations, automations, and scene presets at a glance.*
+
+![Channels view](docs/screenshots/dashboard-targets.PNG)
+
+*Channels — start, stop, and monitor each source-to-device pipeline with live FPS.*
+
+![Live capture preview](docs/screenshots/test-preview-capture.PNG)
+
+*Live preview — inspect the processed capture output in real time before it reaches the LEDs.*
 
 ## Features
 
 ### Screen Capture
 
 - Multi-monitor support with per-target display selection
-- 6 capture engine backends — MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows), Scrcpy (Android via ADB), Camera/Webcam (OpenCV)
+- Capture engine backends: MSS (cross-platform), DXCam, BetterCam, Windows Graphics Capture (Windows only), and Camera/Webcam (OpenCV)
+- Capture from a connected Android phone's screen via scrcpy (ADB) — the device is a *source*; LedGrab itself runs on your desktop
 - Configurable capture regions, FPS, and border width
-- Capture templates for reusable configurations
+- Reusable capture templates
 
 ### LED Device Support
 
-- WLED (HTTP/UDP) with mDNS auto-discovery
+LedGrab speaks many protocols, so a single setup can drive everything from a DIY strip to off-the-shelf smart bulbs:
-- Adalight (serial) — Arduino-compatible LED controllers
+
-- AmbileD (serial)
+![Device type picker](docs/screenshots/devices.PNG)
-- DDP (Distributed Display Protocol, UDP)
+
-- OpenRGB — PC peripherals (keyboard, mouse, RAM, fans, LED strips)
+- **Network LED controllers** — WLED (HTTP/UDP, with mDNS auto-discovery), DDP (Pixelblaze, ESPixelStick, Falcon), Open Pixel Control (OPC), Art-Net / sACN (E1.31), ESP-NOW, and generic WebSocket streaming
-- Serial port auto-detection and baud rate configuration
+- **Serial / direct hardware** — Adalight (Arduino-compatible), AmbiLED, SPI-attached strips (e.g. WS2812B), and USB HID controllers
+- **Smart bulbs & panels** — Philips Hue (Entertainment API), Nanoleaf, Yeelight, WiZ, LIFX, and Govee (Wi-Fi LAN)
+- **Bluetooth LE strips** — SP110E, Triones / HappyLighting, Zengge, and Govee BLE
+- **PC peripherals** — OpenRGB, Razer Chroma, and SteelSeries GameSense (keyboards, mice, RAM, fans, etc.)
+- **Device groups** — combine multiple devices into one logical target
+- Serial port auto-detection and baud-rate configuration
 
 ### Color Processing
 
-- Post-processing filter pipeline: brightness, gamma, saturation, color correction, auto-crop, frame interpolation, pixelation, flip
+- Post-processing filter pipeline: brightness, gamma, saturation, color correction, auto-crop, frame interpolation, pixelation, flip, and more
 - Reusable post-processing templates
-- Color strip sources: audio-reactive, pattern generator, composite layering, audio-to-color mapping
+- Color strip sources: audio-reactive, pattern generator, gradients, composite layering, and audio-to-color mapping
 - Pattern templates with customizable effects
 
 ### Audio Integration
@@ -38,17 +60,20 @@ A Home Assistant integration exposes devices as entities for smart home automati
 - Multichannel audio capture from any system device (input or loopback)
 - WASAPI engine on Windows, Sounddevice (PortAudio) engine on Linux/macOS
 - Per-channel mono extraction
-- Audio-reactive color strip sources driven by frequency analysis
+- Audio filter / processing pipeline feeding audio-reactive color sources driven by frequency analysis
 
 ### Automation
 
-- Profile engine with condition-based switching (time of day, active window, etc.)
+- Automations engine with condition-based rules — switch targets, scenes, or brightness by time of day, active window/process, MQTT, webhooks, or game events
-- Dynamic brightness value sources (schedule-based, scene-aware)
+- Scene presets for one-click lighting changes
-- Key Colors (KC) targets with live WebSocket color streaming
+- Dynamic value sources for brightness and other parameters (schedule-based, weather-based, scene-aware)
+- Weather sources, clock sync, webhooks, and inbound/outbound HTTP endpoints
+- Game integration adapters (e.g. League of Legends)
 
 ### Dashboard
 
-- Web UI at `http://localhost:8080` — no installation needed on the client side
+- Web UI at `http://localhost:8080` — nothing to install on the client side
+- Visual node-graph editor for wiring sources → processing → targets
 - Progressive Web App (PWA) — installable on phones and tablets with offline caching
 - Responsive mobile layout with bottom tab navigation
 - Device management with auto-discovery wizard
@@ -59,32 +84,57 @@ A Home Assistant integration exposes devices as entities for smart home automati
 
 ### Home Assistant Integration
 
-- HACS-compatible custom component
+- HACS-compatible custom component (separate repository)
 - Light, switch, sensor, and number entities per device
-- Real-time metrics via data coordinator
+- Real-time metrics via a data coordinator
 - WebSocket-based live LED preview in HA
 
+## Platforms
+
+LedGrab runs as a desktop / server application:
+
+| Platform | Status | Notes |
+| -------- | ------ | ----- |
+| Windows | ✅ Supported | Installer (`.exe`) and portable ZIP; all capture/audio backends |
+| Linux | ✅ Supported | Tarball and Docker image; X11 capture (Wayland in-container capture not supported) |
+| macOS | ✅ Supported | Runs from source / Docker; MSS capture |
+| Docker | ✅ Supported | Multi-arch container image |
+| Android (TV) | ⚠️ Experimental | An on-device Android-TV build exists (APK attached to releases) but is emulator-verified only and **not officially supported** |
+
+> **There is no production Android app.** Android phones are only supported as a *capture source* (via scrcpy/ADB) from a desktop host. The on-device Android-TV build is experimental.
+
+### Feature support by OS
+
+| Feature | Windows | Linux / macOS | Android TV (experimental) |
+| ------- | ------- | ------------- | ------------------------- |
+| Screen capture | DXCam, BetterCam, WGC, MSS | MSS | MediaProjection; root `screenrecord` (rooted devices) |
+| Webcam capture | OpenCV (DirectShow) | OpenCV (V4L2) | Camera2 (on-demand, while capture is running) |
+| Audio capture | WASAPI, Sounddevice | Sounddevice (PulseAudio/PipeWire) | AudioPlaybackCapture (API 29+) |
+| GPU monitoring | NVIDIA (nvidia-ml-py) | NVIDIA (nvidia-ml-py) | — (CPU/RAM/battery/thermal via `/proc`) |
+| Capture from Android phone | scrcpy (ADB) | scrcpy (ADB) | — (captures its own screen instead) |
+| Notification capture | WinRT | dbus (Linux) | NotificationListenerService |
+| Monitor names | Friendly names (WMI) | Generic ("Display 0") | Single built-in display |
+| LED transports | Network, USB-serial, BLE | Network, USB-serial, BLE | Network, USB-serial (Android driver), BLE (Android bridge) |
+| Automation: window/process conditions | Supported | Partial | Foreground-app condition (UsageStatsManager) |
+
 ## Requirements
 
 - Python 3.11+ (or Docker)
-- A supported LED device on the local network or connected via USB
+- A supported LED device on the local network, connected via USB/serial, or reachable over Bluetooth
-- Windows, Linux, or macOS — all core features work cross-platform
+- Windows, Linux, or macOS
-
-### Platform Notes
-
-| Feature | Windows | Linux / macOS |
-| ------- | ------- | ------------- |
-| Screen capture | DXCam, BetterCam, WGC, MSS | MSS |
-| Webcam capture | OpenCV (DirectShow) | OpenCV (V4L2) |
-| Audio capture | WASAPI, Sounddevice | Sounddevice (PulseAudio/PipeWire) |
-| GPU monitoring | NVIDIA (pynvml) | NVIDIA (pynvml) |
-| Android capture | Scrcpy (ADB) | Scrcpy (ADB) |
-| Monitor names | Friendly names (WMI) | Generic ("Display 0") |
-| Profile conditions | Process/window detection | Not yet implemented |
 
 ## Quick Start
 
-### Docker (recommended)
+### Prebuilt downloads
+
+Grab a ready-to-run build from the [Releases page](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/releases):
+
+- **Windows** — `LedGrab-<version>-setup.exe` (installer, no admin required) or `LedGrab-<version>-win-x64.zip` (portable)
+- **Linux** — `LedGrab-<version>-linux-x64.tar.gz`
+- **Docker** — see below
+- **Android TV** — `.apk` (experimental, see [Platforms](#platforms))
+
+### Docker (recommended for servers)
 
 ```bash
 git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
@@ -115,11 +165,11 @@ export PYTHONPATH=$(pwd)/src    # Linux/Mac
 uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
 ```
 
-Open **http://localhost:8080** to access the dashboard.
+Open <http://localhost:8080> to access the dashboard.
 
-> **Important:** The default API key is `development-key-change-in-production`. Change it before exposing the server outside localhost. See [INSTALLATION.md](INSTALLATION.md) for details.
+> **Network access:** By default, LedGrab allows anonymous access only from `localhost`. Any request from another machine on your LAN is rejected unless you configure an API key (`auth.api_keys`). Set a key before exposing the server on your network — see [INSTALLATION.md](INSTALLATION.md).
 
-See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and Home Assistant setup.
+See [INSTALLATION.md](INSTALLATION.md) for the full installation guide, including configuration, Docker manual builds, and CORS setup.
 
 ## Demo Mode
 
@@ -133,50 +183,9 @@ 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.
+Demo mode uses port **8081**, config file `config/demo_config.yaml`, and stores data under `data/demo/` (separate from production data). It can run alongside the main server.
-
-## Architecture
-
-```text
-ledgrab/
-├── server/                          # Python FastAPI backend
-│   ├── src/ledgrab/
-│   │   ├── main.py                  # Application entry point
-│   │   ├── config.py                # YAML + env var configuration
-│   │   ├── api/
-│   │   │   ├── routes/              # REST + WebSocket endpoints
-│   │   │   └── schemas/             # Pydantic request/response models
-│   │   ├── core/
-│   │   │   ├── capture/             # Screen capture, calibration, pixel processing
-│   │   │   ├── capture_engines/     # MSS, DXCam, BetterCam, WGC, Scrcpy, Camera backends
-│   │   │   ├── devices/             # WLED, Adalight, AmbileD, DDP, OpenRGB clients
-│   │   │   ├── audio/               # Audio capture engines
-│   │   │   ├── filters/             # Post-processing filter pipeline
-│   │   │   ├── processing/          # Stream orchestration and target processors
-│   │   │   └── profiles/            # Condition-based profile automation
-│   │   ├── storage/                 # JSON-based persistence layer
-│   │   ├── static/                  # Web dashboard (vanilla JS, CSS, HTML)
-│   │   │   ├── js/core/             # API client, state, i18n, modals, events
-│   │   │   ├── js/features/         # Feature modules (devices, streams, targets, etc.)
-│   │   │   ├── css/                 # Stylesheets
-│   │   │   └── locales/             # en.json, ru.json, zh.json
-│   │   └── utils/                   # Logging, monitor detection
-│   ├── config/                      # default_config.yaml
-│   ├── tests/                       # pytest suite
-│   ├── Dockerfile
-│   └── docker-compose.yml
-├── docs/
-│   ├── API.md                       # REST API reference
-│   └── CALIBRATION.md               # LED calibration guide
-├── INSTALLATION.md
-└── LICENSE                          # MIT
-```
 
 ## Configuration
 
@@ -187,14 +196,15 @@ server:
   host: "0.0.0.0"
   port: 8080
   log_level: "INFO"
+  cors_origins:
+    - "http://localhost:8080"
 
 auth:
-  api_keys:
+  # Empty (default) → loopback-only anonymous access; LAN requests are rejected.
-    dev: "development-key-change-in-production"
+  # Add a key to enable LAN/remote access (generate one with: openssl rand -hex 32).
-
+  api_keys: {}
-storage:
+  # api_keys:
-  devices_file: "data/devices.json"
+  #   dev: "your-secret-key-here"
-  templates_file: "data/capture_templates.json"
 
 logging:
   format: "json"
@@ -202,25 +212,26 @@ logging:
   max_size_mb: 100
 ```
 
-Environment variable override example: `LEDGRAB_SERVER__PORT=9090`.
+- Application data is stored in a SQLite database (`data/ledgrab.db` by default). Set `LEDGRAB_DATA_DIR` to relocate the data root (database + assets).
+- Environment variable override example: `LEDGRAB_SERVER__PORT=9090`.
+
+See [INSTALLATION.md](INSTALLATION.md) and [`server/.env.example`](server/.env.example) for the full configuration reference.
 
 ## API
 
-The server exposes a REST API (with Swagger docs at `/docs`) covering:
+The server exposes a REST API (with interactive Swagger docs at `/docs`) plus WebSocket endpoints. Resources include:
 
 - **Devices** — CRUD, discovery, validation, state, metrics
-- **Capture Templates** — Screen capture configurations
+- **Capture Templates** & **Picture Sources** — screen capture configuration and stream definitions
-- **Picture Sources** — Screen capture stream definitions
+- **Output Targets** — LED target management, start/stop processing, live color stream
-- **Picture Targets** — LED target management, start/stop processing
+- **Post-Processing Templates** — filter pipeline configurations
-- **Post-Processing Templates** — Filter pipeline configurations
+- **Color Strip Sources**, **Pattern Templates**, **Gradients** — color generation
-- **Color Strip Sources** — Audio, pattern, composite, mapped sources
+- **Audio Sources / Templates / Filters** — audio capture and reactive processing
-- **Audio Sources** — Multichannel and mono audio device configuration
+- **Value Sources**, **Weather Sources**, **Scene Presets** — dynamic parameters and presets
-- **Pattern Templates** — Effect pattern definitions
+- **Automations**, **Webhooks**, **HTTP Endpoints**, **Game Integration** — triggers and rules
-- **Value Sources** — Dynamic brightness/value providers
+- **MQTT** & **Home Assistant** — broker sources and HA integration
-- **Key Colors Targets** — KC targets with WebSocket live color stream
-- **Profiles** — Condition-based automation profiles
 
-All endpoints require API key authentication via `X-API-Key` header or `?token=` query parameter.
+Authentication uses a Bearer token (`Authorization: Bearer <api-key>`) when API keys are configured; loopback requests are anonymous by default. WebSocket connections authenticate via a first-message handshake.
 
 See [docs/API.md](docs/API.md) for the full reference.
 
@@ -253,16 +264,16 @@ ruff check src/ tests/
 Optional extras:
 
 ```bash
-pip install -e ".[perf]"     # High-performance capture engines (Windows)
+pip install -e ".[perf]"            # High-performance capture engines (Windows: DXCam, BetterCam, WGC)
-pip install -e ".[camera]"   # Webcam capture via OpenCV
+pip install -e ".[notifications]"   # OS notification capture (WinRT / dbus)
+pip install -e ".[scrcpy]"          # Capture from an Android phone via scrcpy
+pip install -e ".[ble]"             # Bluetooth LE LED controllers (desktop only)
 ```
 
+## Contributing
+
+Contributions are welcome. LedGrab is MIT-licensed, so you're free to fork, modify, and self-host. Please open an issue or pull request on the [repository](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab).
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](LICENSE). Free and open source.
-
-## Acknowledgments
-
-- [WLED](https://github.com/Aircoookie/WLED) — LED control firmware
-- [FastAPI](https://fastapi.tiangolo.com/) — Python web framework
-- [MSS](https://python-mss.readthedocs.io/) — Cross-platform screen capture

RELEASE_NOTES.md

@@ -1,167 +1,54 @@
-## v0.7.0 (2026-05-26)
+## v0.8.1 (2026-05-28)
 
-A device-support release: **seven new device families**, a unified **pairing UX**,
+### User-facing changes
-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
+#### Features
 
-#### New device types
+##### Multi-broker MQTT devices
 
-- **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))
+- The device editor now shows an MQTT **broker picker** for `device_type=mqtt` (in both the add-device and device-settings modals), wired into load / save / validate / dirty-check / clone. An empty selection means "first available broker"
-- **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))
+- `mqtt_source_id` is now threaded end-to-end through `DeviceCreate` / `DeviceUpdate` / `DeviceResponse` and the device routes; the referenced broker is validated on create **and** update ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- **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
+##### Schema-driven wiring-graph editor
 
-- **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))
+- The visual graph editor now renders ports and edges generically from a backend-served schema (`GET /api/v1/graph/schema`) instead of hard-coding the connectable-field topology in two places — so client and server can no longer drift
+- New `GET /api/v1/graph` returns the full nodes + edges + validation topology, and `GET /api/v1/graph/dependents/{kind}/{id}` reports what references an entity ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
 
-#### Pairing flow
+##### Aggregated snapshot endpoint
 
-- 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))
+- New `GET /api/v1/snapshot` returns all output targets (with processing state + metrics), devices (with brightness), the source / preset / clock lists, and the system block in a **single response** — collapsing the Home Assistant integration's previous ~2N+M request fan-out into one round trip
+- `?include=` fetches only a subset of sections, and an excluded section also skips its server-side work (e.g. cold-cache hardware brightness probes or the blocking NVML performance query) ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
 
-#### MQTT / Zigbee2MQTT
+#### Bug Fixes
 
-- **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))
+- **Graceful shutdown no longer hangs:** uvicorn's graceful-shutdown wait is now bounded (`GRACEFUL_SHUTDOWN_TIMEOUT`, shared by the desktop, Android, and demo launchers). A lingering events WebSocket (which the browser auto-reconnects) used to keep connections from draining, so the lifespan shutdown never ran — leaving LED targets lit and blocking process exit. Ctrl+C / OS shutdown with the UI open now reliably stops targets and checkpoints the DB ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-
+- **Device update error codes:** `update_device` no longer masks an intentional 4xx (e.g. an unknown `mqtt_source_id` or failed group validation) as a generic 500 ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-#### 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
+#### Backend
 
-- **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))
+- **Wiring-graph schema engine** (`api/graph_schema.py`): a pure, unit-tested module that is the single source of truth for which reference fields connect which entity kinds; builds the topology and performs dependency lookup plus cycle / dangling-reference detection without booting the app or any store. The route layer only gathers serialized entities and delegates ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- **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))
+- **Structured access log:** a new middleware emits one structured line per request, attributing it to the authenticated token's friendly label (the key name, **never** the secret) so traffic can be traced to a client (e.g. `homeassistant` vs `android`). uvicorn's own access log is disabled to avoid duplicate lines ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- **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))
+- Shared `validate_mqtt_source_exists` (`_mqtt_validation.py`) deduplicates the MQTT-source existence check between the device and output-target routes ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- **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
+#### Frontend
 
-- **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))
+- Service-worker refresh for the new bundle ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- **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))
+- New suites: graph routes + schema engine, snapshot routes, access-log middleware, `mqtt_source_id` device regressions, and the bounded-shutdown entrypoint. Full suite: **1614 passing** ([a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba))
-- 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>
+<summary>All Commits (1)</summary>
 
-| Hash | Message |
+| Hash | Message | Author |
-|------|---------|
+| ---- | ------- | ------ |
-| [f591e25](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/f591e25) | fix(storage/database): reopen connection on lifespan restart |
+| [a5effba](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/commit/a5effba) | feat: aggregated snapshot + wiring-graph APIs, MQTT device brokers | alexei.dolgolyov |
-| [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_RECONCILE_NOTES.md

@@ -0,0 +1,249 @@
+# Dashboard Reconciliation — Review Notes
+
+*Captured 2026-05-26. Session focused on dashboard + perf-card flicker and per-poll re-rendering.*
+
+*Updated 2026-05-27 — widened the audit beyond the two poll timers and found a **second driver** (server push) plus the **highest-blast-radius site** (`entity-events.ts`). Added §3.5, corrected the "out of scope" reasoning in §5, and confirmed the decision: **commit to the Lit migration**. Implementation deferred — this is still a planning doc, not a spec.*
+
+This is a thinking-aloud document for whoever picks up reconciliation work next (likely me). It captures the bug class, what's already shipped, what's still latent, the decision ladder we walked through, and the recommendation we landed on. It is **not** a spec — treat any code shown as illustrative.
+
+---
+
+## 1. The bug class in one sentence
+
+> Every place a data-driven render — a poll timer **or** a server-pushed `server:*` event — writes `el.innerHTML = ...`, the existing DOM is torn down — even when the new HTML equals the old — which restarts CSS animations, drops focus, skips transitions, and burns wasted DOM mutation cycles.
+
+The symptom only becomes visually loud when the destroyed subtree contains a CSS keyframe animation (e.g. the pulsing `.perf-patches-empty-dot`). Everywhere else the cost is silent: lost transitions, broken focus, wasted layout work. The bug is **load-bearing in the architecture**, not in any single call site — that's why we keep coming back to it.
+
+---
+
+## 2. What landed in commit `f6486f9` (this session)
+
+Tactical work — solves the worst cases, does not change the architecture.
+
+### `server/src/ledgrab/static/js/features/dashboard.ts`
+- Collapsed the two fast-path branches into one. Fast path runs when `structureUnchanged && !forceFullRender` regardless of `running.length`. Previously, **zero running targets meant every poll rebuilt the entire dashboard** even when nothing changed.
+- `_lastSyncClockIds` no longer fingerprints `is_running` — pausing/resuming a clock no longer tears down every card. `_updateSyncClocksInPlace` already handles the toggle.
+- `_updateAutomationsInPlace` now called from the unified fast path. Automation badges were silently going stale on the fast path.
+- `_initFpsCharts` rewritten diff-based: only destroy charts for ids that left or whose canvas was detached by a DOM swap; only create for new ids; only fetch `/api/metrics/history` when there are genuinely new ids needing seed data.
+- Sync-clock pause/resume/reset callers + `server:automation_state_changed` SSE handler now use `loadDashboard()` (no force) — `forceFullRender` is now actually load-bearing, meaning "settings changed, full rebuild required."
+
+### `server/src/ledgrab/static/js/features/perf-charts.ts`
+- `_renderChartSvg` no longer rewrites `innerHTML` per poll. The SVG skeleton (ref line + sys area/line + app line) is built once via `_ensureSparkNodes` and mutated thereafter. WeakMap cache (`_sparkNodeCache`) keyed by host element avoids the per-tick `querySelector` cost.
+- Hidden cards (env-disabled GPU/Temp) skip render entirely.
+- `_fetchPerformance` switched to `fetchWithAuth`.
+- Hardcoded English strings replaced with `t()` calls. New keys: `perf.no_captures`, `perf.captures_count.{one,few,many,other}`, `perf.ratio_of_requested`, `perf.total_count`, `perf.skipped_per_sec`, `perf.tip.now`, `perf.tip.ago` (en/ru/zh).
+- Tooltip reads `dashboardPollInterval` per mousemove tick (was captured at bind time).
+- Dead `<defs><linearGradient>` block removed.
+- `updateTotalCaptureFpsActual` now delegates to `_paintCaptureFpsActualValue` — single code path.
+- `updateActivePatches` / `updateDevices` skip the `innerHTML` write when content signature hasn't changed. This is the direct fix for the "READY TO LAUNCH flickers every update" report — the empty-state dot's CSS pulse no longer resets.
+- Two missing semicolons in `_seedAggregateHistories` (ASI was saving us).
+
+### Reviewer findings addressed (typescript-reviewer pass)
+- **HIGH:** `_metricLabel` was looking up `dashboard.perf.${key}` but the FPS family uses `dashboard.perf.total_fps`, `total_capture_fps`, `total_capture_fps_actual`. Tooltip would have shouted `FPS` / `CAPTURE_FPS` / `CAPTURE_FPS_ACTUAL`. Fixed via explicit `METRIC_LABEL_KEYS` map.
+- **HIGH:** `_ensureSparkNodes` silently coerced `null` children to non-null when the SVG existed but a child was missing. Hardened to validate all four children and rebuild if any are missing.
+
+---
+
+## 3. Hot spots still latent
+
+These are the call sites where `innerHTML` is still written every poll. None are flickering today (no CSS animations on their inner elements), but every one is the same bug shape and will bite the next time someone adds a keyframe / transition / focus target inside.
+
+### `perf-charts.ts`
+
+| Line | Site | Fires per poll? | Notes |
+|------|------|-----------------|-------|
+| 462  | `updateActivePatches` → `listEl.innerHTML` | yes | guarded by signature compare (✓) |
+| 493  | `updateTotalFps` → `valEl.innerHTML` | yes | FPS value, no inner animation |
+| 526  | `updateTotalCaptureFps` → `valEl.innerHTML` | yes | same |
+| 638  | `_paintNetworkValue` → `valEl.innerHTML` | yes | bytes/s value |
+| 655  | `_paintDeviceLatencyValue` → `valEl.innerHTML` (no-devices hint) | yes | hint span |
+| 657  | `_paintDeviceLatencyValue` → `valEl.innerHTML` (offline hint) | yes | hint span |
+| 660  | `_paintDeviceLatencyValue` → `valEl.innerHTML` (ms value) | yes | value |
+| 676  | `_paintSendTimingValue` → `valEl.innerHTML` (idle hint) | yes | hint span |
+| 679  | `_paintSendTimingValue` → `valEl.innerHTML` (ms value) | yes | value |
+| 738  | `_paintErrorsValue` → `valEl.innerHTML` | yes | rate value |
+| 806  | `updateDevices` → `dotsEl.innerHTML` | yes | guarded by signature compare (✓) |
+| 1086 | `_renderValuePair` → `mainEl.innerHTML = appVal` | yes | dual sys/app value |
+| 1088 | `_renderValuePair` → `mainEl.innerHTML = sysVal` | yes | dual sys/app value |
+| 1094 | `_renderValuePair` → `tagEl.innerHTML` (App tag) | mode='both' only | App tag in `both` mode |
+| 1181 | `_applyPerfDataToDom` temp hint | only when cpu_temp_hint_key changes | rare |
+| 1449 | `_paintFpsValue` | seed only | once per init |
+| 1456 | `_paintCaptureFpsValue` | seed only | once per init |
+| 1463 | `_paintCaptureFpsActualValue` (no-captures hint) | yes via live updater | now goes through painter |
+| 1469 | `_paintCaptureFpsActualValue` (value) | yes via live updater | same |
+| 1499 | `_paintErrorsValue` (duplicate of 738) | seed only | once per init |
+| 1823 | tooltip `tip.innerHTML` | per mousemove | rate-limited by hover only |
+
+### `dashboard.ts`
+
+| Line | Site | Fires per poll? | Notes |
+|------|------|-----------------|-------|
+| 275  | `_updateRunningMetrics` → `fpsEl.innerHTML` | per running target | live FPS pill — visible churn |
+| 293  | `_updateRunningMetrics` → `labelEl.innerHTML` (errors label) | per running target | rebuilt each poll |
+| 340  | `_updateAutomationsInPlace` → `btn.innerHTML` | only on enable/disable change | low frequency |
+| 366  | `_updateSyncClocksInPlace` → `btn.innerHTML` | per poll for every clock | wasteful |
+| 975  | `loadDashboard` first-load → `container.innerHTML` | once per init | fine |
+| 989  | `loadDashboard` slow path → `dynamic.innerHTML = dynamicHtml` | only when slow path fires | the **big** swap, scoped already |
+| 1010 | `loadDashboard` error path | rare | fine |
+| 1416 | `subscribeDashboardLayout` clear | rare | fine |
+
+### What this list tells us
+
+- The remaining innerHTML writes are **per-cell value updates** that paint formatted spans (`{value}<span class="perf-fps-unit">fps</span>`). Each rewrite destroys two text nodes + a span every poll across ~10 cells. Not flickering today; will flicker the moment anyone adds an animation to `.perf-fps-unit` or `.perf-fps-ceiling`.
+- The pattern can be killed without architectural change by splitting these into a stable structure (number text node + static unit span) and only updating `textContent` of the number. That's what L3 / Lit would force naturally.
+
+---
+
+## 3.5 Beyond dashboard/perf — push-driven reconciliation
+
+*Added 2026-05-27. The §3 audit was scoped to the two poll timers we were debugging. Widening the `\.innerHTML\s*=` search showed the bug class has a **second driver** and lives outside dashboard/perf too.*
+
+### Two drivers, not one
+
+The teardown is triggered by anything that re-renders **without user intent**:
+
+- **Poll timers** (`setInterval`) — what §2/§3 covered (`dashboard.ts` `_uptimeTimer` + main refresh, `perf-charts.ts` `_pollTimer`).
+- **Server-pushed `server:*` events** — `core/events-ws.ts` turns each WS message into a `server:*` CustomEvent; feature modules listen and re-render through the *same* `innerHTML` paths.
+
+So the one-line bug class in §1 reads "poll- **or** push-driven," not just poll.
+
+### Genuinely-affected sites outside dashboard/perf
+
+| Site | Driver | Shape | Notes |
+| ---- | ------ | ----- | ----- |
+| `core/entity-events.ts` `_invalidateAndReload` | push (`server:entity_changed`, `server:device_health_changed`) | full-**tab** rebuild via `loadTargetsTab` / `loadPictureSources` / `loadAutomations` / `loadIntegrations` | **highest blast radius.** A single pushed entity change tears down and rebuilds an entire tab — losing scroll, focus, open inline editors, restarting card-enter animations. |
+| `features/game-integration.ts` event feed (`_eventMonitorTimer`) | poll (2 s) | `feed.innerHTML = events.slice(0,20).map(...)` | full 20-item list rebuild every 2 s while the panel is open. |
+| `features/game-integration.ts` connection test (`_connectionTestTimer`) | poll | `panel.innerHTML = …` per tick | transient, low frequency. |
+
+`entity-events.ts` already has the **L1 floor applied by hand**: a 600 ms debounce plus a diff check (`oldData === newData`, then length + `id` + `updated_at` compare) that skips the reload when nothing changed. That kills the *no-op* case — but a **real** change still does the full-tab teardown. This is exactly the §4-L1 limitation ("still tears down when content *does* differ"), live across the whole app.
+
+### Counter-examples that already do it right
+
+Two poll loops never flicker because they mutate `textContent` on a **stable structure** instead of rewriting `innerHTML`:
+
+- `core/api.ts` `loadServerInfo` (connection-check poll) — `versionEl.textContent` / `statusEl.textContent`.
+- `features/color-strips/test.ts` FPS sampler (1 s) — `valueEl.textContent` / `avgEl.textContent`.
+
+These are live proof that "stable structure + mutate text node" is the fix — i.e. what L3 / Lit force by construction.
+
+### What this changes about the plan
+
+The §4 ladder was reasoned entirely around **per-cell** rendering, because that was the visible flicker. The push-driven finding surfaces a second, qualitatively different problem:
+
+- **Problem A — cell value churn:** every poll, one value span. Loud only with animations. *Mostly fixed in `f6486f9`.* → wants `setText` / skip-if-unchanged.
+- **Problem B — list/tab teardown:** on change/push, an entire list or tab. Loses scroll/focus/open editors. *Unaddressed.* `entity-events.ts` and the game feed are Problem B. → wants **keyed list reconciliation**.
+
+Problem B is a **list-level** concern, not a cell-level one. In Lit terms it maps to a keyed `repeat()` directive over the tab/list body — the dashboard-card work in Phase 2 already needs this, but `entity-events.ts` needs it for tabs that §5 used to list as "out of scope." This does **not** change the chosen direction (Lit); it adds `entity-events.ts` as a first-class, high-priority target.
+
+---
+
+## 4. Decision ladder
+
+Walked through with the user 2026-05-26. Captured here so we don't re-litigate.
+
+### L1 — drop-in `setInnerHtmlIfChanged` helper
+- **Shape:** `WeakMap<Element, string>` cache; replace every `el.innerHTML = x` with `setInnerHtmlIfChanged(el, x)`.
+- **Wins:** stops the no-change rewrites globally; zero behavior risk; ~30 call-site changes.
+- **Misses:** still tears down DOM when content *does* differ (e.g. FPS row values change every tick); doesn't preserve focus/transition state inside a list.
+- **Verdict:** floor, not ceiling. Worth doing for cells that don't get migrated to L3/Lit.
+
+### L2 — lint guard
+- **Shape:** pre-commit script greps `\.innerHTML\s*=` in `static/js/` outside an allowlist, fails the commit.
+- **Wins:** keeps the discipline; cheap.
+- **Misses:** only useful as a pair with L1+; bare guard with no helper makes contributors angry.
+- **Verdict:** pair with whatever helper we land on.
+
+### L3 — hand-rolled cell-component pattern
+- **Shape:** `defineCell({ html, refs, mount, update, unmount })` + `reconcileList(host, items, binding)` + `setText/setClass/setAttr` mutators. ~150–300 lines of runtime.
+- **Wins:** correct by construction; no dependencies; explicit about what mutates; composes with existing customize panel / color picker.
+- **Misses:** we own the abstraction — it grows over time as we need transitions, async data, focus, devtools, error boundaries. Death by a thousand features.
+- **Verdict:** second-best. Strong contender if zero-deps is a hard constraint.
+
+### Lit migration of polling modules — **recommended**
+- **Shape:** convert each perf cell + each dashboard card cell to a Lit web component. Use `html\`<span>${value}</span>\`` tagged-template + targeted diff. ~5KB gzip added to bundle, no new build step (esbuild handles it).
+- **Wins:** solves the bug class by design; maintained by Google + community; web-components-based so no framework lock-in; composes with vanilla DOM trivially; mental model is close to current template-string idiom; non-polling code can stay vanilla forever.
+- **Misses:** introduces a dependency; contributors learn one more thing; rare edge cases (`@html`-equivalent exists and reintroduces the bug if misused).
+- **Verdict:** best ceiling-to-cost ratio for a small team. Recommended.
+
+### Full framework rewrite (React / Vue / Solid)
+- **Verdict:** overkill. The bug class lives in polling paths; the rest of the app is fine. Spending the migration budget on rebuilding IconSelect / EntitySelect / modals / customize panel / graph editor — none of which are broken — is a bad trade.
+
+---
+
+## 5. Recommendation
+
+**Lit for the polling-heavy modules.**
+
+Migration plan:
+
+### Phase 0 — spike (2-hour time-box)
+- Convert `patches` cell to a Lit component, end to end.
+- Verify it plays nicely with: color picker integration, customize panel layout reorder, `rerenderPerfGrid` reconciliation, `setPerfMode` toggle, hidden-by-env state, the spark tooltip handler.
+- If any of those break in an unfixable way → pivot to L3.
+- If they work → commit to the migration.
+
+### Phase 1 — perf-charts cells
+1. `patches` (already spiked)
+2. `devices`
+3. `fps` / `capture_fps` / `capture_fps_actual` (share a sparkline base class)
+4. `cpu` / `ram` / `gpu` / `temp` (share `_sparkCardHtml` template family)
+5. `network` / `device_latency` / `send_timing` / `errors`
+
+Each is its own PR, dashboard stays working at every step. `renderPerfSection` becomes a registry of Lit components; `rerenderPerfGrid` becomes "reorder existing elements in the grid" (which it mostly already does).
+
+### Phase 2 — dashboard card cells
+6. Output target cards (running variant — biggest payoff, has live FPS + uptime + errors)
+7. Output target cards (stopped variant)
+8. Sync clock cards
+9. Automation cards
+10. Integration (HA / MQTT) cards
+
+These get bigger wins from the migration because they have nested mutable state (FPS pill, errors cell, health dot, action button) that's currently rebuilt per poll via the `_updateRunningMetrics` path.
+
+### Highest-impact: `entity-events.ts` tab reconciliation (sequence early)
+
+`entity-events.ts` (§3.5) is the single highest-blast-radius site and is **not** on the dashboard — it re-renders the Targets / Integrations / Automations tabs on server push. Whether or not those tabs' cells become Lit components, the loader path (`loadTargetsTab` / `loadIntegrations` / `loadAutomations`) should switch from a full `innerHTML` rebuild to a **keyed list reconcile** (a Lit `repeat()` over the tab body). This preserves scroll / focus / open inline editors across pushes. If the goal is "biggest UX win first" rather than "lowest-risk first," sequence this ahead of Phase 2.
+
+### Phase 3 — stopgap helper for the rest
+Add `setInnerHtmlIfChanged` and apply to any remaining vanilla polling sites we don't plan to migrate. Add the L2 lint guard at this point — by now everything that polls is either Lit-managed or uses the helper.
+
+### Out of scope (deliberately) — with one correction (2026-05-27)
+
+- Targets tab, automations editor, integrations, scene presets — these render on-demand, **but they are ALSO re-rendered on server push** via `entity-events.ts` (see §3.5). The original claim that "the bug class doesn't bite them" was **wrong**: a pushed `server:entity_changed` does a full-tab `innerHTML` teardown. The *editor / on-demand views* can stay vanilla, but the **list/tab render that entity-events triggers needs reconciliation** (a keyed list diff) regardless of whether those cells become Lit components. Treat the entity-events reload path as **in-scope** — it is the highest-blast-radius Problem B site.
+- Color strips editor, graph editor, settings — genuinely on-demand, no push re-render path, stay vanilla.
+- Transport bar cells (CPU/Mem chip in the top bar) — read from the same perf payload, can be migrated opportunistically but not urgent.
+
+---
+
+## 6. Open questions to settle before committing
+
+These came up during the discussion and weren't resolved:
+
+1. **Bundle-size budget.** Is +5KB acceptable? Current bundle is 2.7MB so this is noise — but worth confirming there isn't a strict cap (e.g. for slow networks / Android Chaquopy embed).
+2. **Contributor model.** If the project will grow to multiple contributors, Lit's smaller community vs React's is a recruiting tradeoff. Currently solo-ish, so probably moot.
+3. **Android TV target.** Chaquopy embed serves the same bundle. Lit works fine in any modern browser — Android TV WebView is Chromium-based. Should be a no-op but verify in Phase 0 spike.
+4. **Long-term framework intent.** If there's a chance we ever migrate to React/Vue/Solid for the rest of the app, doing Lit now is *not* lock-in (web components are standard), but it does add a second mental model. Probably fine; just naming the tradeoff.
+5. **Customize panel.** The drag-reorder code in `dashboard-customize.ts` mutates `.dashboard-section` DOM directly. Lit components reorder cleanly via `moveBefore` / `insertBefore` since they're just elements, but the dnd library needs to treat them as opaque drag handles. Phase 0 spike should confirm.
+
+---
+
+## 7. Pointers
+
+- Source files most relevant:
+  - `server/src/ledgrab/static/js/features/dashboard.ts`
+  - `server/src/ledgrab/static/js/features/perf-charts.ts`
+  - `server/src/ledgrab/static/js/features/dashboard-layout.ts` (cell ordering + visibility)
+  - `server/src/ledgrab/static/js/features/dashboard-customize.ts` (drag-reorder UI)
+  - `server/src/ledgrab/static/js/core/card-modes.ts` (mode toggle that hangs off section headers)
+  - `server/src/ledgrab/static/js/core/entity-events.ts` (push-driven tab reloads — §3.5, highest blast radius)
+  - `server/src/ledgrab/static/js/core/events-ws.ts` (WS → `server:*` CustomEvent dispatch)
+  - `server/src/ledgrab/static/js/features/game-integration.ts` (2 s event-feed list rebuild — §3.5)
+- Most recent reconciliation commit: `f6486f9`.
+- Related skill files in `~/.claude/skills/`: `frontend-patterns`, `documentation-lookup` (for Lit docs via Context7).
+- Locale convention: `perf.*` for cross-card primitives, `dashboard.perf.*` for cell titles.
+
+---
+
+## 8. If this doc gets stale
+
+If you read this and the perf cells are already Lit components — delete this file. If you read this and there's a new flicker / focus / transition bug nobody can explain — search for `\.innerHTML\s*=` in `static/js/features/` **and `static/js/core/`** (`entity-events` lives in core) and you've probably found it. For *state loss on a server event* (scroll jump, focus drop, an inline editor closing itself), look at the `server:*` listeners in `core/entity-events.ts` first.

TODO.md

@@ -201,9 +201,19 @@ caller off the legacy path, then delete it.
 - [x] Field on `device_config.MQTTConfig`
 - [x] `MQTTLEDClient` acquires runtime in `connect()`, releases in `close()`
 - [x] Provider threads `mqtt_manager` via `ProviderDeps`
-- [ ] Device editor: MQTT source picker shown for `device_type=mqtt` *(UI still
+- [x] Device editor: MQTT source picker shown for `device_type=mqtt`. Turned
-      pending — backend accepts the field, but the device-create form doesn't
+      out the API layer was *also* missing it (the TODO's "backend accepts the
-      expose it yet)*
+      field" was wrong — `mqtt_source_id` lived in `device_store` +
+      `device_config.MQTTConfig` but was dropped by `DeviceCreate/Update/Response`
+      and the routes). Added: schema fields + route threading + referenced-source
+      validation (`_validate_mqtt_source_exists`, mirrors output_targets) +
+      `except HTTPException: raise` guard in `update_device` (it was masking its
+      own 4xx as 500). Frontend: broker `EntitySelect` (reusing `mqttSourcesCache`)
+      in both the add-device (`device-discovery.ts`) and settings
+      (`devices.ts`) modals — shown for `device_type=mqtt`, wired into
+      load/save/validate/dirty-check/clone. Empty = "first available broker".
+      4 regression tests in `test_devices_routes.py::TestMqttSourceId`; full
+      suite 1567 passing; en/ru/zh keys added.
 
 ### Phase 5 — `AutomationEngine`
 
@@ -213,8 +223,11 @@ caller off the legacy path, then delete it.
 ### Phase 6 — `api/routes/system.py`
 
 - [x] Replace integration status with `mqtt_manager.get_all_sources_status()`
-- [ ] Update frontend dashboard payload (MQTT widget now expects a list of
+- [x] Update frontend dashboard payload (MQTT widget now expects a list of
-      sources instead of a single `enabled`/`connected` pair — surface in UI)
+      sources instead of a single `enabled`/`connected` pair — surface in UI).
+      Done: `dashboard.ts` `_renderMQTTIntegrationCard` renders one card per
+      `mqttStatus.connections` entry; `_updateIntegrationsInPlace` iterates the
+      list.
 
 ### Phase 7 — Startup migration
 
@@ -980,3 +993,123 @@ After phase 1 the codebase will have 3 fresh examples of "ping the LAN, listen f
       - LOW: Nanoleaf `.port` property added; pair-then-create E2E test
         added.
       - Tests: 1379 pass (+21 regression tests).
+
+## Graph editor — "full control of wiring via graph" (in progress)
+
+Goal: make the visual graph a first-class wiring control surface, not just a
+viewer. Driven by the ULTRA-DEEP review (findings A1–A5, B1–B6, C1–C6, D1–D6).
+
+### Done (NOT yet committed — awaiting review/commit)
+
+- [x] **A1** Undo/redo wired to connect/detach/move (was dead code); inverse ops
+      throw on failure so the stack can't silently desync.
+- [x] **A2** Manual node layout persists to `localStorage` (`graph_node_positions`),
+      cleared on relayout.
+- [x] **A3** Scene-preset disambiguation — deactivation scene now reachable via a
+      field picker (was always picking the first match).
+- [x] **B6** Edge field labels (revealed on zoom ≥ 0.9).
+- [x] **C3** Health overlay — broken refs (referrer exists, target missing),
+      dependency cycles, orphans; node warning badges + an issues toolbar button.
+- [x] **D1** `GET /api/v1/graph/schema` — authoritative connectable-field registry
+      (`api/graph_schema.py`, pure + unit-tested).
+- [x] **D2** `GET /api/v1/graph` (nodes+edges+validation) and
+      `GET /api/v1/graph/dependents/{kind}/{id}`.
+- [x] **D4** `POST /api/v1/graph/validate-connection` — existence + source-kind +
+      cycle pre-flight; frontend validates before every write (fails open if the
+      endpoint is unreachable). List/double-nested fields rejected.
+- [x] **B2** Drop-on-node connect — empty top-level slots are now wireable (drop a
+      source onto any compatible node body, not just an existing port).
+- [x] **C4** Overwrite-occupied-slot confirm + delete-with-dependents warning
+      (single delete only; bulk keeps the batch confirm).
+- [x] **D5** Create-and-connect — drag a port onto empty canvas → pick a compatible
+      new entity kind → it's created and auto-wired (kind-scoped watcher).
+- [x] **D6 (read-only half)** "Export graph (JSON)" toolbar action.
+- [x] Custom per-entity `icon` + `icon_color` now render on graph nodes (parity
+      with custom node colours; fallback to kind/subtype glyph).
+- [x] **B1** Edit single-level **BindableFloat** value slots from the graph
+      (`brightness`, `smoothing`, `intensity`, `scale`, `speed`, … on
+      color_strip_source; `brightness`/`transition` on output_target). Subtype-safe
+      (only offers slots the target entity actually has). Writes the partial
+      `{ <slot>: { source_id } }` payload → backend `Bindable*.apply_update` merges,
+      preserving the static value. Verified data-safe (no `from_raw`/value-reset path).
+- [x] Render the two functional value-source references `buildGraph` was missing —
+      `value_source.value_source_id` (gradient_map → inner value source) and
+      `value_source.color_strip_source_id` (css_extract → strip). Both are runtime-
+      resolved and already drag-editable; now visible/detachable in the graph.
+- [x] **B4 foundation:** backend schema now authoritative about graph-editability
+      (`is_editable()` + `editable` flag in `/graph/schema`); `validate-connection`
+      hardened to reject non-editable fields (colour/list/double-nested), not just lists.
+- [x] **B4 drift guard + gap fixes:** `checkSchemaDrift()` (graph-connections.ts) warns
+      once if the frontend `CONNECTION_MAP` editable set diverges from `/graph/schema`
+      (the automated "10-step checklist"). Surfacing it found 3 real gaps; fixed 2:
+      `color_strip_source.input_source_id` + `processing_template_id` are now drag-editable
+      (processed-strip wiring; `apply_update` is partial-safe). The 3rd —
+      `device.default_css_processing_template_id` — is intentionally NOT drag-editable
+      (the device PUT route isn't partial-safe; a one-field PUT could null the URL) and is
+      in the drift-check exclude set. Also broadened `_availableMatches` to hide any slot
+      the target entity doesn't expose (subtype-accurate; refs are always-emitted so empty
+      slots stay wireable). Review also caught a **dead `output_target.picture_source_id`
+      slot** (no output target stores it — not a field/schema, never emitted) — removed
+      from both registries + `buildGraph`.
+- [x] **Comprehensive review pass (4 subagents: backend/frontend-core/orchestrator/security).**
+      Findings fixed:
+      - **CRITICAL (security):** `GET /api/v1/graph` leaked plaintext **webhook tokens**
+        (`asdict` recursed `Automation.rules[].token`, an auth-equivalent secret). Fixed with
+        **field-projection** — `serialize_entity_for_graph()` / `graph_field_roots()` project
+        each entity to only `{id, name, subtype, reference-roots}`; secrets can't survive.
+        Added a structural regression test asserting no projection root is secret-bearing for
+        any kind (drift-proof boundary) + a token-drop test.
+      - MEDIUM: added missing `value_source.clock_id` (AnimatedColorValueSource → sync_clock)
+        to the backend registry for topology/dependents completeness (drift-excluded on the
+        frontend — value-source PUT needs a `source_type` discriminator, so it's editor-only).
+      - MEDIUM/LOW: `CSS.escape` on the markIssues id selector; grouped/clarified
+        `_DRIFT_EXCLUDE`; fixed the stale `_availableMatches` JSDoc; documented the
+        `checkSchemaDrift` forward-reference. Orchestrator + frontend-core + security: APPROVE.
+- Verification: `npm --prefix server run typecheck` + `run build` clean; ruff clean;
+  graph backend tests 35 pass; full backend suite green. ~8 code-review passes,
+  all CRITICAL/HIGH findings fixed.
+
+### Left to do (deferred)
+
+- [x] **BindableColor slots** — CHECKED, decision: keep read-only (won't fix).
+      Value sources are scalar-only (`ValueStream.get_value() -> float`) and every
+      colour consumer (`color_strip/single.py`, `effect_stream.py`) reads the static
+      RGB via `bcolor()`, ignoring `source_id`. So a value_source cannot drive a
+      colour — wiring `color`/`color_peak`/… would be a dead binding. Documented in
+      `api/graph_schema.py` next to the BindableColor entries. (Would only become
+      viable if a colour-producing value-source type is added.)
+- [~] **B4 — delete the frontend `CONNECTION_MAP` duplication.**
+      - [x] **Foundation done:** the backend schema now carries an authoritative
+        `editable` flag per field (`is_editable()` in `api/graph_schema.py`, mirroring
+        the frontend `_isEditable`: top-level refs + single-level BindableFloat slots;
+        NOT colour/list/double-nested). `validate-connection` is hardened to reject any
+        non-editable field (was list-only). `editable` is surfaced in `/graph/schema`.
+      - [ ] **Remaining (the refactor):** frontend fetches `/graph/schema` on load and
+        derives connection metadata + edges from it (port the `extract_refs` dot-path/list
+        grammar to TS), keeping only a tiny `kind → {endpoint, cache}` write-routing table;
+        then delete the field-level `CONNECTION_MAP` + the `buildGraph` edge loops
+        (graph-connections.ts / graph-layout.ts). Removes the 10-step sync checklist in
+        `contexts/graph-editor.md`. **A backend apply-write endpoint is NOT required** —
+        keep the proven per-entity PUT. Risk: regressing drag-connect/bindable; keep a
+        dev drift-check (frontend editable set vs `/graph/schema`) during the transition.
+        Note: frontend `CONNECTION_MAP` also has inert `ha_source_id`/`gradient_id` entries
+        (no graph node kind) — drop them, the backend schema already omits them.
+- [ ] **D6 — blueprint import/instantiate.** Export exists; the apply half (serialize
+      a selected subgraph's topology + entities, re-import with id remapping, conflict
+      handling) is large and data-integrity-sensitive (see Data Migration Policy in
+      CLAUDE.md). Scope as its own feature.
+- [ ] **List-slot editing** (composite `layers[]`, mapped `zones[]`, scene preset
+      `targets[]`) — needs an element index in the write + validate paths
+      (`validate_connection` currently rejects list fields). Edit via entity modal
+      for now.
+
+### Notes / decisions
+
+- The backend `CONNECTION_SCHEMA` (`api/graph_schema.py`) is the authoritative
+  superset; it already declares the bindable + list + value_source-chain edges. The
+  frontend `CONNECTION_MAP` still owns write-routing (endpoint/cache) — that's the
+  only reason it survives (see B4).
+- Bindable edges render dashed (`.graph-edge-nested`) but ARE editable — the dashed
+  style intentionally distinguishes value bindings from structural edges.
+- `validate-connection` and `dependents` fail **open/safe** on the frontend so the
+  graph keeps working against an older server without these endpoints.

android/app/build.gradle.kts

@@ -41,7 +41,7 @@ android {
         // in CI).  See ledgrabVersionCode above.  Was stuck at 1 before —
         // sideload updates silently refused to install.
         versionCode = ledgrabVersionCode
-        versionName = "0.7.0"
+        versionName = "0.8.1"
 
         // ABI selection. Detect armeabi-v7a wheel presence and opt the
         // ABI in only when the matching pydantic-core wheel is on disk —

android/app/src/main/AndroidManifest.xml

@@ -35,10 +35,48 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <!-- FOREGROUND_SERVICE_CAMERA (API 34+): required to keep camera access while
+         the app is backgrounded during on-device webcam capture. The service is
+         promoted with the `camera` FGS type ONLY when CAMERA is already granted
+         (see CaptureService.onStartCommand) — unlike audio playback capture (which
+         rides the MediaProjection token under the mediaProjection type), the camera
+         has no such coupling and needs its own FGS type to survive backgrounding. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
 
     <!-- POST_NOTIFICATIONS for Android 13+ foreground service notification -->
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
+    <!-- RECORD_AUDIO for on-device system-playback capture (AudioPlaybackCapture,
+         API 29+) feeding audio-reactive lighting. Runtime "dangerous" permission,
+         requested in MainActivity; capture degrades gracefully when denied.
+         Playback capture runs under the existing mediaProjection FGS type, so no
+         FOREGROUND_SERVICE_MICROPHONE / microphone FGS type is needed (that would
+         only be required if the mic-fallback path ran inside the service). -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+
+    <!-- CAMERA for on-device webcam capture (Camera2). Runtime "dangerous"
+         permission, requested in MainActivity gated on FEATURE_CAMERA_ANY so
+         camera-less TV boxes never see the prompt; capture degrades gracefully
+         when denied. The camera is opened ON DEMAND (only while a camera
+         capture source is active). To keep capturing after the app is
+         backgrounded, the service is promoted with the `camera` FGS type
+         (FOREGROUND_SERVICE_CAMERA above) — but only when CAMERA is already
+         granted, so a camera-less / not-yet-granted box never risks a failed
+         service start. -->
+    <uses-permission android:name="android.permission.CAMERA" />
+
+    <!-- PACKAGE_USAGE_STATS — read the foreground app for the "Application"
+         automation rule (foreground app -> activate scene) via UsageStatsManager.
+         A special-access permission: it can't be granted at runtime; the user
+         toggles it under Settings > Usage access (opened from MainActivity).
+         tools:ignore="ProtectedPermissions" silences the build warning that this
+         is a system/signature-level permission — it is honoured as a user-grantable
+         special access. NO QUERY_ALL_PACKAGES is needed: matching only compares the
+         foreground package NAME, and the app picker uses LauncherApps. -->
+    <uses-permission
+        android:name="android.permission.PACKAGE_USAGE_STATS"
+        tools:ignore="ProtectedPermissions" />
+
     <!-- 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" />
@@ -63,6 +101,15 @@
         android:name="android.hardware.usb.host"
         android:required="false" />
 
+    <!-- Camera hardware — for on-device webcam capture. required=false so
+         camera-less TV boxes (the common case) still install; the camera
+         engine simply reports no displays on such devices. camera.any covers
+         built-in (front/back) and external/USB-UVC cameras the platform
+         routes through Camera2. -->
+    <uses-feature
+        android:name="android.hardware.camera.any"
+        android:required="false" />
+
     <application
         android:name=".LedGrabApp"
         android:allowBackup="false"
@@ -95,13 +142,30 @@
              PROPERTY_SPECIAL_USE_FGS_SUBTYPE rationale below. -->
         <service
             android:name=".CaptureService"
-            android:foregroundServiceType="mediaProjection|specialUse"
+            android:foregroundServiceType="mediaProjection|specialUse|camera"
             android:exported="false">
             <property
                 android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
                 android:value="Root-mode screen capture for ambient LED sync. Uses /system/bin/screenrecord on rooted devices to avoid MediaProjection's persistent capture indicator overlay, which is required for the always-on ambient-lighting use case." />
         </service>
 
+        <!-- Notification capture — a NotificationListenerService bound by
+             system_server. exported="true" is REQUIRED here (the system binds
+             it cross-process) and intentionally diverges from CaptureService
+             (exported="false"); access is gated by the system-held
+             BIND_NOTIFICATION_LISTENER_SERVICE permission, so no new
+             <uses-permission> is needed. The user grants access via
+             Settings > Notification access (opened from MainActivity). -->
+        <service
+            android:name=".LedGrabNotificationListener"
+            android:label="@string/notification_listener_label"
+            android:exported="true"
+            android:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE">
+            <intent-filter>
+                <action android:name="android.service.notification.NotificationListenerService" />
+            </intent-filter>
+        </service>
+
         <!-- 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

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

@@ -0,0 +1,234 @@
+package com.ledgrab.android
+
+import android.annotation.SuppressLint
+import android.media.AudioAttributes
+import android.media.AudioFormat
+import android.media.AudioPlaybackCaptureConfiguration
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import android.media.projection.MediaProjection
+import android.os.Build
+import android.util.Log
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * Captures audio with [AudioRecord] and pushes interleaved float32 PCM to
+ * the LedGrab Python server via [PythonBridge], where the
+ * `android_audio_engine` feeds it into the unchanged audio-analysis
+ * pipeline.
+ *
+ * Two sources:
+ *  - [start] — system playback capture via `AudioPlaybackCapture` (API 29+),
+ *    reusing the same [MediaProjection] token the app already holds for
+ *    screen capture. This is the primary path on the consent flow.
+ *  - [startMic] — microphone fallback (`AudioSource.MIC`) for paths with no
+ *    MediaProjection (root mode) or API < 29.
+ *
+ * Mirrors [ScreenCapture]'s shape: a dedicated capture thread, a single
+ * reusable cross-JNI buffer (no per-block allocation → no GC churn on
+ * low-end TV boxes), and graceful teardown in [stop].
+ *
+ * The capture format is negotiated by [AudioRecord]; the **actual**
+ * channel count and sample rate are read back and forwarded to
+ * `configureAudio` so the Python analyzer's interleaving matches the bytes
+ * we push (e.g. a stereo request that the device satisfies as mono).
+ */
+class AudioCapture(
+    private val projection: MediaProjection?,
+    private val bridge: PythonBridge,
+    private val sampleRate: Int = 48000,
+    private val channels: Int = 2,
+    private val chunkFrames: Int = 1024,
+) {
+    companion object {
+        private const val TAG = "AudioCapture"
+        private const val BYTES_PER_FLOAT = 4
+    }
+
+    private var audioRecord: AudioRecord? = null
+    private var captureThread: Thread? = null
+    @Volatile private var running = false
+
+    /**
+     * Start system playback capture (API 29+). Requires the app to hold
+     * RECORD_AUDIO and a valid [projection]. Returns true if capture began.
+     */
+    @SuppressLint("MissingPermission")
+    fun start(): Boolean {
+        if (running) return true
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+            Log.i(TAG, "Playback capture needs API 29+; skipping (have ${Build.VERSION.SDK_INT})")
+            return false
+        }
+        val proj = projection
+        if (proj == null) {
+            Log.i(TAG, "No MediaProjection; playback capture unavailable")
+            return false
+        }
+
+        val config = AudioPlaybackCaptureConfiguration.Builder(proj)
+            .addMatchingUsage(AudioAttributes.USAGE_MEDIA)
+            .addMatchingUsage(AudioAttributes.USAGE_GAME)
+            .addMatchingUsage(AudioAttributes.USAGE_UNKNOWN)
+            .build()
+
+        val record = try {
+            AudioRecord.Builder()
+                .setAudioFormat(audioFormat())
+                .setBufferSizeInBytes(bufferBytes())
+                .setAudioPlaybackCaptureConfig(config)
+                .build()
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to build playback AudioRecord: ${e.message}")
+            return false
+        }
+        return begin(record, "playback")
+    }
+
+    /**
+     * Start microphone capture (fallback). Works on API 24+ and needs no
+     * MediaProjection. Requires RECORD_AUDIO. Returns true if capture began.
+     *
+     * ⚠️ SECURITY/POLICY: currently UNWIRED (no caller). Microphone capture is
+     * a materially different posture than playback capture — it records real
+     * room audio (bystander voices). Before wiring this into [CaptureService]:
+     *  - add FOREGROUND_SERVICE_MICROPHONE permission + the `microphone` FGS
+     *    type (on API 34+ the service is killed without it), and
+     *  - add the Play Store privacy disclosure for microphone use,
+     *  - re-trigger a security review.
+     * Do NOT call this from inside the foreground service without the above.
+     */
+    @SuppressLint("MissingPermission")
+    fun startMic(): Boolean {
+        if (running) return true
+        val record = try {
+            AudioRecord.Builder()
+                .setAudioSource(MediaRecorder.AudioSource.MIC)
+                .setAudioFormat(audioFormat())
+                .setBufferSizeInBytes(bufferBytes())
+                .build()
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to build mic AudioRecord: ${e.message}")
+            return false
+        }
+        return begin(record, "mic")
+    }
+
+    /** Stop capturing and release all resources. Idempotent. */
+    fun stop() {
+        running = false
+        // AudioRecord.stop() unblocks a pending READ_BLOCKING read within
+        // milliseconds, so the loop sees running=false and returns well inside
+        // the 500ms join window — release() below won't race a live read.
+        // (Mirrors ScreenCapture's bounded join.)
+        runCatching { audioRecord?.stop() }
+        captureThread?.let { runCatching { it.join(500) } }
+        captureThread = null
+        runCatching { audioRecord?.release() }
+        audioRecord = null
+        runCatching { bridge.shutdownAudio() }
+        Log.i(TAG, "Audio capture stopped")
+    }
+
+    // ── internals ──────────────────────────────────────────────────────
+
+    private fun begin(record: AudioRecord, mode: String): Boolean {
+        if (record.state != AudioRecord.STATE_INITIALIZED) {
+            Log.e(TAG, "AudioRecord ($mode) failed to initialize")
+            runCatching { record.release() }
+            return false
+        }
+        val actualChannels = record.channelCount.coerceAtLeast(1)
+        val actualRate = record.sampleRate
+
+        // Confirm recording actually started before reporting success —
+        // startRecording() can throw (exclusive-capture contention) or
+        // leave the record in a non-recording state, in which case read()
+        // would only ever return errors.
+        val started = runCatching { record.startRecording() }.isSuccess &&
+            record.recordingState == AudioRecord.RECORDSTATE_RECORDING
+        if (!started) {
+            Log.e(TAG, "AudioRecord ($mode) failed to start recording")
+            runCatching { record.release() }
+            return false
+        }
+
+        // Recording confirmed — tell Python the real negotiated format
+        // before frames flow, so the analyzer's channel/sample-rate match
+        // the interleaving we push.
+        bridge.configureAudio(actualRate, actualChannels, chunkFrames)
+
+        audioRecord = record
+        running = true
+        captureThread = Thread(
+            { captureLoop(record, actualChannels) },
+            "LedGrab-AudioCapture",
+        ).also { it.start() }
+        Log.i(TAG, "Audio capture started ($mode, sr=$actualRate ch=$actualChannels chunk=$chunkFrames)")
+        return true
+    }
+
+    /**
+     * Blocking read loop. Accumulates into fixed `chunkFrames * channels`
+     * float blocks and pushes only COMPLETE blocks — [AudioRecord.read]
+     * returns a variable count, so partial reads are stitched here rather
+     * than handed to Python as ragged chunks (the analyzer requires
+     * whole-frame, ≤ chunk-size blocks).
+     */
+    private fun captureLoop(record: AudioRecord, actualChannels: Int) {
+        val blockFloats = chunkFrames * actualChannels
+        val floatBuf = FloatArray(blockFloats)
+        // Reusable little-endian byte buffer — Python copies on push, so the
+        // same backing array is safe to overwrite next block. Default
+        // ByteBuffer order is BIG_ENDIAN, which would corrupt every sample;
+        // LITTLE_ENDIAN matches numpy's native float32 on all Android ABIs.
+        val byteBuf = ByteArray(blockFloats * BYTES_PER_FLOAT)
+        val floatView = ByteBuffer.wrap(byteBuf).order(ByteOrder.LITTLE_ENDIAN).asFloatBuffer()
+
+        var filled = 0
+        while (running) {
+            val n = record.read(floatBuf, filled, blockFloats - filled, AudioRecord.READ_BLOCKING)
+            if (n < 0) {
+                if (running) {
+                    // A negative read (e.g. ERROR_DEAD_OBJECT after an audio-route
+                    // change, ERROR_INVALID_OPERATION) means this AudioRecord is
+                    // finished. Deactivate the Python engine so is_available() stops
+                    // advertising a dead stream and the audio-reactive consumer isn't
+                    // left polling an empty queue forever. We're on the capture thread,
+                    // so we can't call stop() (it would self-join) — just flip running
+                    // and shut the engine down; onDestroy's stop() releases the record.
+                    Log.w(TAG, "AudioRecord.read error: $n — stopping audio capture")
+                    running = false
+                    runCatching { bridge.shutdownAudio() }
+                }
+                break
+            }
+            filled += n
+            if (filled < blockFloats) continue
+
+            floatView.clear()
+            floatView.put(floatBuf, 0, blockFloats)
+            bridge.pushAudio(byteBuf)
+            filled = 0
+        }
+    }
+
+    private fun channelMask(): Int =
+        if (channels >= 2) AudioFormat.CHANNEL_IN_STEREO else AudioFormat.CHANNEL_IN_MONO
+
+    private fun audioFormat(): AudioFormat =
+        AudioFormat.Builder()
+            .setEncoding(AudioFormat.ENCODING_PCM_FLOAT)
+            .setSampleRate(sampleRate)
+            .setChannelMask(channelMask())
+            .build()
+
+    private fun bufferBytes(): Int {
+        val minBuf = AudioRecord.getMinBufferSize(sampleRate, channelMask(), AudioFormat.ENCODING_PCM_FLOAT)
+        // A few blocks of headroom so a slow consumer doesn't overrun the
+        // hardware buffer between reads.
+        val want = chunkFrames * channels * BYTES_PER_FLOAT * 4
+        return if (minBuf > 0) maxOf(minBuf, want) else want
+    }
+}

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

@@ -0,0 +1,411 @@
+package com.ledgrab.android
+
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.pm.PackageManager
+import android.graphics.ImageFormat
+import android.hardware.camera2.CameraCaptureSession
+import android.hardware.camera2.CameraCharacteristics
+import android.hardware.camera2.CameraDevice
+import android.hardware.camera2.CameraManager
+import android.media.Image
+import android.media.ImageReader
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.SystemClock
+import android.util.Log
+import android.util.Size
+import android.view.Surface
+import com.chaquo.python.PyObject
+import com.chaquo.python.Python
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withTimeout
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Android camera bridge exposed to the Python server via Chaquopy.
+ *
+ * Wraps the Camera2 API into synchronous, blocking calls that can be
+ * invoked from a Python thread (Chaquopy proxy threads are real OS
+ * threads).  The physical camera is opened **on demand** — Python's
+ * `android_camera_engine` calls [startCamera] when a capture stream
+ * initializes and [stopCamera] when it cleans up, so the camera-in-use
+ * indicator and battery cost are limited to actual use.
+ *
+ * Each captured frame is converted YUV_420_888 → RGB and pushed to the
+ * Python engine's `push_frame`, mirroring how [ScreenCapture] feeds
+ * `mediaprojection_engine`. Camera2 callbacks run on a private
+ * [HandlerThread] so they never touch the main looper.
+ *
+ * Python callers access the singleton via
+ *   `jclass("com.ledgrab.android.CameraBridge").INSTANCE` — see
+ *   `server/src/ledgrab/core/capture_engines/android_camera_engine.py`.
+ */
+object CameraBridge {
+    private const val TAG = "CameraBridge"
+    private const val ENGINE_MODULE = "ledgrab.core.capture_engines.android_camera_engine"
+    private const val OPEN_TIMEOUT_MS = 8_000L
+    private const val MAX_IMAGES = 2
+    private const val TARGET_FPS = 20
+    // "auto" capture size — balanced for ambient LED sampling (the LED
+    // pipeline downscales anyway), kept modest so the per-frame YUV→RGB
+    // conversion stays cheap on low-end TV boxes.
+    private const val DEFAULT_W = 1280
+    private const val DEFAULT_H = 720
+    private const val BYTES_PER_RGB = 3
+
+    @Volatile private var appContext: Context? = null
+
+    // Dedicated looper thread so Camera2 callbacks don't land on main.
+    private val camThread = HandlerThread("LedGrab-Camera").also { it.start() }
+    private val camHandler = Handler(camThread.looper)
+
+    // Active session state — guarded by [lock]. One camera at a time.
+    private val lock = Any()
+    private var cameraDevice: CameraDevice? = null
+    private var captureSession: CameraCaptureSession? = null
+    private var imageReader: ImageReader? = null
+    @Volatile private var running = false
+    private var activeIndex = -1
+
+    // Cached Python engine module handle for the per-frame push fast path.
+    @Volatile private var engineModule: PyObject? = null
+
+    // Reusable conversion buffers — sized once per session (output size is
+    // fixed for the session), reused to avoid per-frame GC churn on TV boxes.
+    private var rgbBuffer: ByteArray? = null
+    private var yBuf: ByteArray? = null
+    private var uBuf: ByteArray? = null
+    private var vBuf: ByteArray? = null
+
+    // Monotonic frame pacing (mirrors ScreenCapture's accumulator).
+    private val frameIntervalNanos = 1_000_000_000L / TARGET_FPS.coerceAtLeast(1)
+    private var nextFrameNanos = 0L
+
+    /** Called once from [LedGrabApp.onCreate] to bind the application context. */
+    @JvmStatic
+    fun init(context: Context) {
+        appContext = context.applicationContext
+    }
+
+    /**
+     * Enumerate cameras as a JSON array string the Python engine parses:
+     *   `[{"index":0,"name":"Back camera","facing":"back","cameraId":"0"}, ...]`
+     *
+     * Indices are stable (positional in [CameraManager.cameraIdList]) so
+     * Python's `display_index` maps 1:1 to [startCamera]'s `index`.
+     * Enumeration needs no CAMERA permission. Returns `[]` on any error.
+     */
+    @JvmStatic
+    fun listCameras(): String {
+        val arr = JSONArray()
+        val ctx = appContext
+        if (ctx == null) {
+            Log.w(TAG, "listCameras: context not bound (init not called)")
+            return arr.toString()
+        }
+        try {
+            val mgr = ctx.getSystemService(Context.CAMERA_SERVICE) as CameraManager
+            mgr.cameraIdList.forEachIndexed { idx, id ->
+                val facing = facingOf(mgr, id)
+                val name = when (facing) {
+                    "front" -> "Front camera"
+                    "back" -> "Back camera"
+                    "external" -> "External camera $idx"
+                    else -> "Camera $idx"
+                }
+                arr.put(
+                    JSONObject()
+                        .put("index", idx)
+                        .put("name", name)
+                        .put("facing", facing)
+                        .put("cameraId", id),
+                )
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "listCameras failed: ${e.message}")
+        }
+        return arr.toString()
+    }
+
+    /**
+     * Open camera [index] and start streaming RGB frames to Python.
+     * Blocks until the capture session is configured (or fails/times out).
+     *
+     * Returns false — without throwing across the JNI boundary — when the
+     * CAMERA permission is missing, the index is out of range, or the
+     * device/session fails to configure. Closes any previously-open camera
+     * first (one active at a time).
+     */
+    @SuppressLint("MissingPermission")
+    @JvmStatic
+    fun startCamera(index: Int, width: Int, height: Int): Boolean {
+        synchronized(lock) {
+            closeLocked()
+
+            val ctx = appContext ?: run {
+                Log.w(TAG, "startCamera: context not bound")
+                return false
+            }
+            if (ctx.checkSelfPermission(Manifest.permission.CAMERA)
+                != PackageManager.PERMISSION_GRANTED
+            ) {
+                Log.w(TAG, "startCamera: CAMERA permission not granted")
+                return false
+            }
+
+            val mgr = ctx.getSystemService(Context.CAMERA_SERVICE) as CameraManager
+            val ids = try {
+                mgr.cameraIdList
+            } catch (e: Exception) {
+                Log.w(TAG, "startCamera: cameraIdList failed: ${e.message}")
+                return false
+            }
+            if (index < 0 || index >= ids.size) {
+                Log.w(TAG, "startCamera: index $index out of range (${ids.size} cameras)")
+                return false
+            }
+            val cameraId = ids[index]
+            val size = chooseSize(mgr, cameraId, width, height) ?: run {
+                Log.w(TAG, "startCamera: no YUV output sizes for camera $index")
+                return false
+            }
+
+            val reader = ImageReader.newInstance(
+                size.width, size.height, ImageFormat.YUV_420_888, MAX_IMAGES,
+            )
+            // Size the conversion buffers once for this session.
+            rgbBuffer = ByteArray(size.width * size.height * BYTES_PER_RGB)
+            yBuf = null; uBuf = null; vBuf = null
+            nextFrameNanos = SystemClock.elapsedRealtimeNanos()
+            reader.setOnImageAvailableListener({ r -> onFrame(r) }, camHandler)
+
+            return try {
+                runBlocking {
+                    withTimeout(OPEN_TIMEOUT_MS) {
+                        // Publish each resource to its field as soon as it exists so
+                        // closeLocked() (in the catch) can release it if a LATER step
+                        // throws. Assigning only after setRepeatingRequest succeeds
+                        // would orphan the opened CameraDevice on a createSession /
+                        // setRepeatingRequest failure (camera stuck on; subsequent
+                        // opens fail with CAMERA_IN_USE).
+                        imageReader = reader
+                        val device = openCamera(mgr, cameraId)
+                        cameraDevice = device
+                        val session = createSession(device, reader.surface)
+                        captureSession = session
+                        val request = device.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW)
+                            .apply { addTarget(reader.surface) }
+                            .build()
+                        session.setRepeatingRequest(request, null, camHandler)
+                        activeIndex = index
+                        running = true
+                        Log.i(TAG, "Camera $index opened (${size.width}x${size.height} @ ${TARGET_FPS}fps)")
+                        true
+                    }
+                }
+            } catch (e: Exception) {
+                Log.e(TAG, "startCamera($index) failed: ${e.message}")
+                // imageReader/cameraDevice/captureSession are now whatever got
+                // assigned before the failure — closeLocked releases each exactly
+                // once (idempotent, runCatching-wrapped).
+                closeLocked()
+                false
+            }
+        }
+    }
+
+    /** Stop streaming and release the camera. Idempotent; safe if not started. */
+    @JvmStatic
+    fun stopCamera() {
+        synchronized(lock) { closeLocked() }
+        Log.i(TAG, "Camera stopped")
+    }
+
+    // ── internals ────────────────────────────────────────────────────────
+
+    private fun facingOf(mgr: CameraManager, id: String): String =
+        when (mgr.getCameraCharacteristics(id).get(CameraCharacteristics.LENS_FACING)) {
+            CameraCharacteristics.LENS_FACING_FRONT -> "front"
+            CameraCharacteristics.LENS_FACING_BACK -> "back"
+            CameraCharacteristics.LENS_FACING_EXTERNAL -> "external"
+            else -> "unknown"
+        }
+
+    /** Pick the supported YUV size closest in area to the request (or the
+     *  balanced default for `auto`/0). */
+    private fun chooseSize(mgr: CameraManager, cameraId: String, reqW: Int, reqH: Int): Size? {
+        val map = mgr.getCameraCharacteristics(cameraId)
+            .get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) ?: return null
+        val sizes = map.getOutputSizes(ImageFormat.YUV_420_888)
+        if (sizes == null || sizes.isEmpty()) return null
+        val targetArea = (if (reqW > 0) reqW else DEFAULT_W).toLong() *
+            (if (reqH > 0) reqH else DEFAULT_H)
+        return sizes.minByOrNull { kotlin.math.abs(it.width.toLong() * it.height - targetArea) }
+    }
+
+    @SuppressLint("MissingPermission")
+    private suspend fun openCamera(mgr: CameraManager, cameraId: String): CameraDevice =
+        suspendCancellableCoroutine { cont ->
+            mgr.openCamera(cameraId, object : CameraDevice.StateCallback() {
+                override fun onOpened(device: CameraDevice) {
+                    if (cont.isActive) cont.resume(device) else device.close()
+                }
+
+                override fun onDisconnected(device: CameraDevice) {
+                    device.close()
+                    if (cont.isActive) cont.resumeWithException(IllegalStateException("camera disconnected"))
+                }
+
+                override fun onError(device: CameraDevice, error: Int) {
+                    device.close()
+                    if (cont.isActive) cont.resumeWithException(IllegalStateException("camera error $error"))
+                }
+            }, camHandler)
+        }
+
+    @Suppress("DEPRECATION")
+    private suspend fun createSession(device: CameraDevice, surface: Surface): CameraCaptureSession =
+        suspendCancellableCoroutine { cont ->
+            // createCaptureSession(List, callback, handler) is deprecated at
+            // API 30 but is the correct API down to minSdk 24 (the
+            // SessionConfiguration overload is API 28+).
+            device.createCaptureSession(
+                listOf(surface),
+                object : CameraCaptureSession.StateCallback() {
+                    override fun onConfigured(session: CameraCaptureSession) {
+                        if (cont.isActive) cont.resume(session)
+                    }
+
+                    override fun onConfigureFailed(session: CameraCaptureSession) {
+                        if (cont.isActive) cont.resumeWithException(IllegalStateException("session configure failed"))
+                    }
+                },
+                camHandler,
+            )
+        }
+
+    /** ImageReader callback — paced, converts YUV→RGB, pushes to Python. */
+    private fun onFrame(reader: ImageReader) {
+        if (!running) {
+            runCatching { reader.acquireLatestImage()?.close() }
+            return
+        }
+        val now = SystemClock.elapsedRealtimeNanos()
+        if (now < nextFrameNanos) {
+            runCatching { reader.acquireLatestImage()?.close() }
+            return
+        }
+        val image = runCatching { reader.acquireLatestImage() }.getOrNull() ?: return
+        try {
+            val w = image.width
+            val h = image.height
+            val out = ensureRgbBuffer(w * h * BYTES_PER_RGB)
+            yuv420ToRgb(image, out, w, h)
+            pushFrame(out, w, h)
+            nextFrameNanos += frameIntervalNanos
+            if (now - nextFrameNanos > frameIntervalNanos * 4) {
+                nextFrameNanos = now + frameIntervalNanos
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "frame processing error: ${e.message}")
+        } finally {
+            runCatching { image.close() }
+        }
+    }
+
+    private fun ensureRgbBuffer(size: Int): ByteArray {
+        val buf = rgbBuffer
+        if (buf != null && buf.size == size) return buf
+        return ByteArray(size).also { rgbBuffer = it }
+    }
+
+    /**
+     * Stride-aware YUV_420_888 → packed RGB (3 bytes/px) using BT.601
+     * fixed-point coefficients. Handles both planar and semi-planar
+     * (NV21-like, pixelStride 2) chroma layouts via the plane strides.
+     */
+    private fun yuv420ToRgb(image: Image, out: ByteArray, width: Int, height: Int) {
+        val planes = image.planes
+        val yPlane = planes[0]
+        val uPlane = planes[1]
+        val vPlane = planes[2]
+
+        val yRowStride = yPlane.rowStride
+        val yPixStride = yPlane.pixelStride
+        val uRowStride = uPlane.rowStride
+        val uPixStride = uPlane.pixelStride
+        val vRowStride = vPlane.rowStride
+        val vPixStride = vPlane.pixelStride
+
+        // Copy each plane to a reusable array for fast indexed access
+        // (ByteBuffer absolute-get per pixel is far slower).
+        val yByteBuf = yPlane.buffer
+        val uByteBuf = uPlane.buffer
+        val vByteBuf = vPlane.buffer
+        val yArr = ensurePlane(yBuf, yByteBuf.remaining()).also { yBuf = it }
+        val uArr = ensurePlane(uBuf, uByteBuf.remaining()).also { uBuf = it }
+        val vArr = ensurePlane(vBuf, vByteBuf.remaining()).also { vBuf = it }
+        yByteBuf.get(yArr, 0, yArr.size)
+        uByteBuf.get(uArr, 0, uArr.size)
+        vByteBuf.get(vArr, 0, vArr.size)
+
+        var o = 0
+        for (row in 0 until height) {
+            val yRowBase = row * yRowStride
+            val uvRow = row shr 1
+            val uRowBase = uvRow * uRowStride
+            val vRowBase = uvRow * vRowStride
+            for (col in 0 until width) {
+                val y = (yArr[yRowBase + col * yPixStride].toInt() and 0xFF)
+                val uvCol = col shr 1
+                val u = (uArr[uRowBase + uvCol * uPixStride].toInt() and 0xFF) - 128
+                val v = (vArr[vRowBase + uvCol * vPixStride].toInt() and 0xFF) - 128
+                // BT.601 full-range, fixed-point (<<16).
+                var r = y + ((91881 * v) shr 16)
+                var g = y - ((22554 * u + 46802 * v) shr 16)
+                var b = y + ((116130 * u) shr 16)
+                if (r < 0) r = 0 else if (r > 255) r = 255
+                if (g < 0) g = 0 else if (g > 255) g = 255
+                if (b < 0) b = 0 else if (b > 255) b = 255
+                out[o++] = r.toByte()
+                out[o++] = g.toByte()
+                out[o++] = b.toByte()
+            }
+        }
+    }
+
+    /** Return [cached] if it already fits [n] bytes, else a fresh array. */
+    private fun ensurePlane(cached: ByteArray?, n: Int): ByteArray =
+        if (cached != null && cached.size == n) cached else ByteArray(n)
+
+    private fun pushFrame(rgb: ByteArray, width: Int, height: Int) {
+        val module = engineModule ?: runCatching {
+            Python.getInstance().getModule(ENGINE_MODULE)
+        }.getOrNull()?.also { engineModule = it } ?: return
+        try {
+            module.callAttr("push_frame", rgb, width, height)
+        } catch (e: Exception) {
+            Log.w(TAG, "push_frame failed: ${e.message}")
+        }
+    }
+
+    /** Tear down the active session. Caller holds [lock]. */
+    private fun closeLocked() {
+        running = false
+        activeIndex = -1
+        runCatching { imageReader?.setOnImageAvailableListener(null, null) }
+        runCatching { captureSession?.stopRepeating() }
+        runCatching { captureSession?.close() }
+        captureSession = null
+        runCatching { cameraDevice?.close() }
+        cameraDevice = null
+        runCatching { imageReader?.close() }
+        imageReader = null
+    }
+}

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

@@ -4,9 +4,11 @@ import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.PendingIntent
+import android.Manifest
 import android.app.Service
 import android.content.Context
 import android.content.Intent
+import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
 import android.media.projection.MediaProjection
 import android.media.projection.MediaProjectionManager
@@ -85,6 +87,7 @@ class CaptureService : Service() {
     private var bridge: PythonBridge? = null
     private var screenCapture: ScreenCapture? = null
     private var rootCapture: RootScreenrecord? = null
+    private var audioCapture: AudioCapture? = null
     private var mediaProjection: MediaProjection? = null
 
     // Service-scoped coroutine scope for the root-capture watchdog.
@@ -110,11 +113,25 @@ class CaptureService : Service() {
         val url = "http://$localIp:$SERVER_PORT"
         try {
             val type = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
-                if (useRoot) {
+                var t = if (useRoot) {
                     ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE
                 } else {
                     ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
                 }
+                // On-demand webcam capture opens the camera from this service.
+                // To retain camera access once the app is backgrounded (the
+                // always-on ambient-lighting case), API 34+ requires the camera
+                // FGS type. Add it ONLY when CAMERA is already granted — promoting
+                // with the camera type without the runtime permission throws and
+                // would kill the whole service on the (common) camera-less or
+                // not-yet-granted box. If CAMERA is granted later, it takes effect
+                // on the next Start (matches the audio/permission UX).
+                if (checkSelfPermission(Manifest.permission.CAMERA) ==
+                    PackageManager.PERMISSION_GRANTED
+                ) {
+                    t = t or ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
+                }
+                t
             } else {
                 0
             }
@@ -338,6 +355,25 @@ class CaptureService : Service() {
             onProjectionStopped = { stopSelf() },
         ).also { it.start() }
 
+        // Reuse the same projection to capture system playback audio so
+        // audio-reactive lighting works on-device (API 29+, RECORD_AUDIO
+        // granted). Best-effort: screen capture and the server keep running
+        // if audio is unavailable. Started AFTER ScreenCapture so the
+        // projection's callback is already registered.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q &&
+            checkSelfPermission(Manifest.permission.RECORD_AUDIO) ==
+            PackageManager.PERMISSION_GRANTED
+        ) {
+            audioCapture = AudioCapture(projection, newBridge).also { ac ->
+                if (!ac.start()) {
+                    Log.i(TAG, "Playback audio capture unavailable — continuing without audio")
+                    audioCapture = null
+                }
+            }
+        } else {
+            Log.i(TAG, "RECORD_AUDIO not granted or API < 29 — audio-reactive capture disabled")
+        }
+
         Log.i(TAG, "LedGrab service started (MediaProjection) — web UI at $url")
     }
 
@@ -351,6 +387,10 @@ class CaptureService : Service() {
         screenCapture?.stop()
         screenCapture = null
 
+        // Stop audio before the server: stop() calls bridge.shutdownAudio().
+        audioCapture?.stop()
+        audioCapture = null
+
         rootCapture?.stop()
         rootCapture = null
 

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

@@ -0,0 +1,154 @@
+package com.ledgrab.android
+
+import android.app.AppOpsManager
+import android.app.usage.UsageEvents
+import android.app.usage.UsageStatsManager
+import android.content.Context
+import android.content.pm.LauncherApps
+import android.os.Build
+import android.os.Process
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Foreground-app + installed-app bridge exposed to the Python server via Chaquopy.
+ *
+ * Backs the Android implementation of the "Application" automation rule
+ * (foreground app -> activate scene). Desktop detects the foreground process via
+ * Win32 ctypes in ``platform_detector.py``; Android has no such API, so this
+ * bridge wraps two in-platform services into synchronous calls a Python thread
+ * can invoke (Chaquopy proxy threads are real OS threads):
+ *
+ *   - [getForegroundPackage] via [UsageStatsManager] (needs PACKAGE_USAGE_STATS,
+ *     a special-access permission granted from Settings — see MainActivity).
+ *   - [listLaunchableApps] via [LauncherApps] for the automation editor's app
+ *     picker (no QUERY_ALL_PACKAGES needed — getActivityList is the sanctioned
+ *     launchable-app enumeration API).
+ *   - [hasUsageAccess] so the server / UI can detect the missing grant.
+ *
+ * Detection only ever string-compares the foreground *package name*, so no label
+ * resolution / package visibility is required at match time.
+ *
+ * Python callers access the singleton via
+ *   `jclass("com.ledgrab.android.ForegroundAppBridge").INSTANCE` — see
+ *   `server/src/ledgrab/core/automations/platform_detector.py`.
+ */
+object ForegroundAppBridge {
+    private const val TAG = "ForegroundAppBridge"
+
+    // Trailing window for queryEvents. queryEvents reports discrete foreground
+    // transitions (not "current app"), and events can lag a few seconds, so we
+    // look back far enough to reliably catch the latest MOVE_TO_FOREGROUND while
+    // staying recent enough not to report a stale app on the ~1s automation tick.
+    private const val WINDOW_MS = 10_000L
+
+    @Volatile private var appContext: Context? = null
+
+    /** Called once from [LedGrabApp.onCreate] to bind the application context. */
+    @JvmStatic
+    fun init(context: Context) {
+        appContext = context.applicationContext
+    }
+
+    /**
+     * Package name of the most recently foregrounded app, or null when none is
+     * found in the trailing window, Usage Access is not granted, or on any error.
+     * Never throws across the JNI boundary.
+     */
+    @JvmStatic
+    fun getForegroundPackage(): String? {
+        val ctx = appContext ?: run {
+            Log.w(TAG, "getForegroundPackage: context not bound (init not called)")
+            return null
+        }
+        return try {
+            val usm = ctx.getSystemService(Context.USAGE_STATS_SERVICE) as? UsageStatsManager
+                ?: return null
+            val end = System.currentTimeMillis()
+            val events = usm.queryEvents(end - WINDOW_MS, end)
+            val event = UsageEvents.Event()
+            var latestPkg: String? = null
+            var latestTs = Long.MIN_VALUE
+            while (events.hasNextEvent()) {
+                events.getNextEvent(event)
+                // ACTIVITY_RESUMED (API 29+) shares the value of the legacy
+                // MOVE_TO_FOREGROUND constant, so the single check covers both.
+                // >= (not >) so that on an exact-timestamp tie the later-iterated
+                // event wins — events arrive chronologically, so that is the most
+                // recent foreground transition.
+                if (event.eventType == UsageEvents.Event.MOVE_TO_FOREGROUND &&
+                    event.timeStamp >= latestTs
+                ) {
+                    latestTs = event.timeStamp
+                    latestPkg = event.packageName
+                }
+            }
+            latestPkg
+        } catch (e: Exception) {
+            // SecurityException when access is missing, plus any service error.
+            Log.w(TAG, "getForegroundPackage failed: ${e.message}")
+            null
+        }
+    }
+
+    /** Whether the user has granted Usage Access (PACKAGE_USAGE_STATS) to this app. */
+    @JvmStatic
+    fun hasUsageAccess(): Boolean {
+        val ctx = appContext ?: return false
+        return try {
+            val appOps = ctx.getSystemService(Context.APP_OPS_SERVICE) as? AppOpsManager
+                ?: return false
+            val mode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                appOps.unsafeCheckOpNoThrow(
+                    AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), ctx.packageName,
+                )
+            } else {
+                @Suppress("DEPRECATION")
+                appOps.checkOpNoThrow(
+                    AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), ctx.packageName,
+                )
+            }
+            mode == AppOpsManager.MODE_ALLOWED
+        } catch (e: Exception) {
+            Log.w(TAG, "hasUsageAccess failed: ${e.message}")
+            false
+        }
+    }
+
+    /**
+     * Launchable apps as a JSON array string the Python server parses:
+     *   `[{"package":"com.netflix.mediaclient","label":"Netflix"}, ...]`
+     *
+     * Uses [LauncherApps.getActivityList] (launcher + leanback launchables) —
+     * no QUERY_ALL_PACKAGES. De-duplicated by package, sorted by label.
+     * Returns `[]` on any error.
+     */
+    @JvmStatic
+    fun listLaunchableApps(): String {
+        val arr = JSONArray()
+        val ctx = appContext ?: run {
+            Log.w(TAG, "listLaunchableApps: context not bound (init not called)")
+            return arr.toString()
+        }
+        try {
+            val launcher = ctx.getSystemService(Context.LAUNCHER_APPS_SERVICE) as? LauncherApps
+                ?: return arr.toString()
+            val seen = HashSet<String>()
+            val items = ArrayList<Pair<String, String>>()
+            for (info in launcher.getActivityList(null, Process.myUserHandle())) {
+                val pkg = info.applicationInfo?.packageName ?: continue
+                if (!seen.add(pkg)) continue
+                val label = info.label?.toString().takeUnless { it.isNullOrBlank() } ?: pkg
+                items.add(pkg to label)
+            }
+            items.sortBy { it.second.lowercase() }
+            for ((pkg, label) in items) {
+                arr.put(JSONObject().put("package", pkg).put("label", label))
+            }
+        } catch (e: Exception) {
+            Log.w(TAG, "listLaunchableApps failed: ${e.message}")
+        }
+        return arr.toString()
+    }
+}

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

@@ -51,6 +51,13 @@ class LedGrabApp : Application() {
         // Bind application context for the BLE bridge so Python can
         // scan and connect to BLE LED controllers.
         BleBridge.init(this)
+        // Bind application context for the camera bridge so Python can
+        // enumerate cameras and open them on demand (webcam capture).
+        CameraBridge.init(this)
+        // Bind application context for the foreground-app bridge so Python can
+        // detect the foreground app (Application automation rule) and list
+        // launchable apps for the editor's picker.
+        ForegroundAppBridge.init(this)
 
         // Pre-warm the API key on a background thread. First-launch
         // generation does a SharedPreferences.commit() (synchronous

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

@@ -0,0 +1,97 @@
+package com.ledgrab.android
+
+import android.app.Notification
+import android.service.notification.NotificationListenerService
+import android.service.notification.StatusBarNotification
+import android.util.Log
+import com.chaquo.python.Python
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.Executors
+
+/**
+ * Captures posted OS notifications and forwards the posting app's display
+ * label to the Python notification pipeline, where the existing
+ * `NotificationColorStripSource` fires its one-shot LED effect.
+ *
+ * Direction is Kotlin -> Python via the process-global Chaquopy instance
+ * (NOT a per-[CaptureService] [PythonBridge]): `system_server` binds this
+ * service independently of [CaptureService], so it resolves Python itself.
+ * The Python receiver (`os_notification_listener.push_notification`) is a
+ * no-op whenever the server/listener isn't running, so a notification
+ * arriving before — or after — a capture session is safely ignored.
+ */
+class LedGrabNotificationListener : NotificationListenerService() {
+
+    // Serial executor: the Python receiver does a (non-concurrency-safe) history
+    // disk write and may play a sound, so pushes must not overlap. Off the main
+    // looper to keep the system service responsive.
+    private val pushExecutor = Executors.newSingleThreadExecutor()
+
+    // packageName -> resolved human-readable label. Matches the app_name the
+    // Windows/Linux backends pass, so per-app colors/filters keep working.
+    // Naturally bounded by the number of notification-posting apps (tens) and
+    // cleared with the process — no eviction needed.
+    private val labelCache = ConcurrentHashMap<String, String>()
+
+    override fun onNotificationPosted(sbn: StatusBarNotification?) {
+        val notification = sbn ?: return
+
+        // The Python server (and thus the listener) only exists during a capture
+        // session. isRunning is a coarse early-out — the authoritative gate is the
+        // Python receiver's None-check — but it avoids needless JNI churn here.
+        if (!CaptureService.isRunning) return
+
+        // Filter notifications that should never drive an effect:
+        //  - ongoing (media transport, downloads): not user-facing "alerts"
+        //  - group summaries: duplicate their child notifications
+        //  - our own foreground-service notification: would self-trigger
+        if (notification.isOngoing) return
+        if ((notification.notification.flags and Notification.FLAG_GROUP_SUMMARY) != 0) return
+        if (notification.packageName == packageName) return
+
+        val label = resolveAppLabel(notification.packageName)
+
+        pushExecutor.execute {
+            try {
+                Python.getInstance()
+                    .getModule(PY_MODULE)
+                    .callAttr("push_notification", label)
+            } catch (t: Throwable) {
+                // Never crash a system-bound service. Python.getInstance() throws
+                // IllegalStateException if Python.start() hasn't run (e.g. the
+                // service was bound at boot before the app process initialized).
+                // Log at debug — the label is potentially sensitive on a shared TV.
+                Log.d(TAG, "push_notification failed: ${t.message}")
+            }
+        }
+    }
+
+    /** Resolve (and cache) a package's human-readable label; fall back to the package name. */
+    private fun resolveAppLabel(pkg: String): String {
+        labelCache[pkg]?.let { return it }
+        val resolved = runCatching {
+            val info = packageManager.getApplicationInfo(pkg, 0)
+            packageManager.getApplicationLabel(info).toString()
+        }.getOrDefault(pkg)
+        labelCache[pkg] = resolved
+        return resolved
+    }
+
+    override fun onListenerConnected() {
+        Log.i(TAG, "Notification listener connected")
+    }
+
+    override fun onListenerDisconnected() {
+        Log.i(TAG, "Notification listener disconnected")
+    }
+
+    override fun onDestroy() {
+        pushExecutor.shutdown()
+        super.onDestroy()
+    }
+
+    companion object {
+        private const val TAG = "LedGrabNotifListener"
+        private const val PY_MODULE = "ledgrab.core.processing.os_notification_listener"
+    }
+}

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

@@ -24,6 +24,7 @@ import android.widget.ImageView
 import android.widget.LinearLayout
 import android.widget.ScrollView
 import android.widget.TextView
+import androidx.core.app.NotificationManagerCompat
 import androidx.core.content.ContextCompat
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import com.google.zxing.BarcodeFormat
@@ -53,7 +54,11 @@ class MainActivity : Activity() {
         private const val SERVER_PORT = 8080
         private const val REQUEST_MEDIA_PROJECTION = 1001
         private const val REQUEST_POST_NOTIFICATIONS = 1002
+        private const val REQUEST_RECORD_AUDIO = 1003
+        private const val REQUEST_CAMERA = 1004
         private const val QR_SIZE_PX = 560
+        private const val NOTIF_PREFS = "ledgrab_notif"
+        private const val KEY_NOTIF_ACCESS_PROMPTED = "notif_access_prompted"
     }
 
     // Stopped-state views (always inflated).
@@ -63,6 +68,8 @@ class MainActivity : Activity() {
     private lateinit var versionText: TextView
     private lateinit var autostartCheck: CheckBox
     private lateinit var autostartPrefs: AutostartPrefs
+    private lateinit var grantNotificationButton: Button
+    private lateinit var grantUsageAccessButton: Button
 
     // Running-state views (lazy-inflated via ViewStub).
     private lateinit var runningPanelStub: ViewStub
@@ -106,6 +113,8 @@ class MainActivity : Activity() {
         toggleButton = findViewById(R.id.toggle_button)
         versionText = findViewById(R.id.version_text)
         autostartCheck = findViewById(R.id.autostart_check)
+        grantNotificationButton = findViewById(R.id.grant_notification_button)
+        grantUsageAccessButton = findViewById(R.id.grant_usage_access_button)
 
         val versionName = packageManager.getPackageInfo(packageName, 0).versionName
         versionText.text = getString(R.string.version_prefix, versionName ?: "?")
@@ -126,8 +135,11 @@ class MainActivity : Activity() {
             autostartCheck.visibility = View.GONE
         }
 
+        grantNotificationButton.setOnClickListener { openNotificationListenerSettings() }
+        grantUsageAccessButton.setOnClickListener { openUsageAccessSettings() }
         toggleButton.setOnClickListener { startCapture() }
 
+        updateStoppedPermissionButtons()
         updateUI()
     }
 
@@ -148,12 +160,16 @@ class MainActivity : Activity() {
 
     override fun onResume() {
         super.onResume()
+        if (!::stoppedPanel.isInitialized) return
         // Restart the pulse if we returned to the foreground while the
-        // service is still running. The running panel's view may have
+        // service is still running. The running panel's view may have been
-        // been recreated; ensureRunningPanelInflated already keys off
+        // recreated; ensureRunningPanelInflated already keys off the field
-        // the field reference.
+        // reference. When stopped, refresh the notification-access button —
-        if (CaptureService.isRunning && ::stoppedPanel.isInitialized) {
+        // the user may have just granted/revoked access in Settings.
+        if (CaptureService.isRunning) {
             updateUI()
+        } else {
+            updateStoppedPermissionButtons()
         }
     }
 
@@ -196,6 +212,8 @@ class MainActivity : Activity() {
 
     private fun startRootCaptureService() {
         ensureNotificationPermission()
+        ensureNotificationListenerAccess()
+        ensureCameraPermission()
         ContextCompat.startForegroundService(this, CaptureService.createRootIntent(this))
         updateUI()
     }
@@ -215,6 +233,9 @@ class MainActivity : Activity() {
 
     private fun startCaptureService(resultCode: Int, resultData: Intent) {
         ensureNotificationPermission()
+        ensureNotificationListenerAccess()
+        ensureAudioPermission()
+        ensureCameraPermission()
         val intent = CaptureService.createIntent(this, resultCode, resultData)
         ContextCompat.startForegroundService(this, intent)
         updateUI()
@@ -471,4 +492,128 @@ class MainActivity : Activity() {
             }
         }
     }
+
+    /**
+     * Request RECORD_AUDIO (API 29+) so the capture service can capture
+     * system playback audio for audio-reactive lighting.  Fire-and-forget,
+     * like [ensureNotificationPermission]: capture still works without it
+     * (just no audio), so we don't block on the result.  If first granted
+     * here, audio becomes available on the next Start.
+     */
+    private fun ensureAudioPermission() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) return
+        if (checkSelfPermission(Manifest.permission.RECORD_AUDIO)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            @Suppress("DEPRECATION")
+            requestPermissions(
+                arrayOf(Manifest.permission.RECORD_AUDIO),
+                REQUEST_RECORD_AUDIO,
+            )
+        }
+    }
+
+    /**
+     * Request CAMERA so the capture service can open the device camera for
+     * on-device webcam capture.  Fire-and-forget, like [ensureAudioPermission]:
+     * capture still works without it (just no camera engine), so we don't block
+     * on the result.  Gated on actual camera hardware via FEATURE_CAMERA_ANY so
+     * camera-less TV boxes (the common case) never see the prompt.  The camera
+     * is opened on demand only while a camera source is active — granting this
+     * does not keep the camera on.  If first granted here, the camera engine
+     * becomes available on the next Start.
+     */
+    private fun ensureCameraPermission() {
+        if (!packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA_ANY)) return
+        if (checkSelfPermission(Manifest.permission.CAMERA)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            @Suppress("DEPRECATION")
+            requestPermissions(
+                arrayOf(Manifest.permission.CAMERA),
+                REQUEST_CAMERA,
+            )
+        }
+    }
+
+    /** Whether the user has granted notification-listener access to this app. */
+    private fun isNotificationAccessGranted(): Boolean =
+        NotificationManagerCompat.getEnabledListenerPackages(this).contains(packageName)
+
+    /** Open the system Notification-access screen (manual affordance / re-grant). */
+    private fun openNotificationListenerSettings() {
+        runCatching {
+            startActivity(Intent(Settings.ACTION_NOTIFICATION_LISTENER_SETTINGS))
+        }.onFailure { Log.w(TAG, "Notification-access settings unavailable: ${it.message}") }
+    }
+
+    /**
+     * Whether Usage Access (PACKAGE_USAGE_STATS) is granted — needed by the
+     * foreground-app automation rule. Delegates to the bridge's AppOps check.
+     */
+    private fun isUsageAccessGranted(): Boolean = ForegroundAppBridge.hasUsageAccess()
+
+    /**
+     * Open the system Usage-Access screen so the user can grant LedGrab access
+     * for the foreground-app automation rule. Falls back to the generic Settings
+     * screen on TV-box OEM builds that strip the dedicated intent.
+     */
+    private fun openUsageAccessSettings() {
+        runCatching {
+            startActivity(Intent(Settings.ACTION_USAGE_ACCESS_SETTINGS))
+        }.onFailure {
+            Log.w(TAG, "Usage-access settings unavailable: ${it.message}")
+            runCatching { startActivity(Intent(Settings.ACTION_SETTINGS)) }
+        }
+    }
+
+    /**
+     * Prompt-once-then-remember: the first time capture starts without
+     * notification-listener access, open the settings screen so the user can
+     * grant it — then never nag again (the manual "Grant notification access"
+     * button stays available). Fire-and-forget like [ensureNotificationPermission].
+     */
+    private fun ensureNotificationListenerAccess() {
+        if (isNotificationAccessGranted()) return
+        val prefs = getSharedPreferences(NOTIF_PREFS, MODE_PRIVATE)
+        if (prefs.getBoolean(KEY_NOTIF_ACCESS_PROMPTED, false)) return
+        prefs.edit().putBoolean(KEY_NOTIF_ACCESS_PROMPTED, true).apply()
+        openNotificationListenerSettings()
+    }
+
+    /**
+     * Show each "Grant <permission> access" button only while that access is
+     * missing, then re-wire the D-pad focus chain. Called on create and on resume
+     * (access can change in Settings while we're backgrounded). The usage-access
+     * button is a passive affordance (no auto-prompt at capture start) — the
+     * primary guidance is the web-UI banner when an Android app rule needs it.
+     */
+    private fun updateStoppedPermissionButtons() {
+        if (!::grantNotificationButton.isInitialized) return
+        grantNotificationButton.visibility =
+            if (isNotificationAccessGranted()) View.GONE else View.VISIBLE
+        grantUsageAccessButton.visibility =
+            if (isUsageAccessGranted()) View.GONE else View.VISIBLE
+        wireStoppedFocusChain()
+    }
+
+    /**
+     * Link the visible stopped-panel controls into a single up/down D-pad chain.
+     * The optional controls (the grant-access buttons and the root-only autostart
+     * checkbox) may be GONE, so the chain is computed from whatever is visible —
+     * a static nextFocus pointing at a GONE view would strand the focus on a TV
+     * remote.
+     */
+    private fun wireStoppedFocusChain() {
+        val chain = listOfNotNull(
+            toggleButton,
+            grantNotificationButton.takeIf { it.visibility == View.VISIBLE },
+            grantUsageAccessButton.takeIf { it.visibility == View.VISIBLE },
+            autostartCheck.takeIf { it.visibility == View.VISIBLE },
+        )
+        chain.forEachIndexed { i, view ->
+            view.nextFocusUpId = (chain.getOrNull(i - 1) ?: view).id
+            view.nextFocusDownId = (chain.getOrNull(i + 1) ?: view).id
+        }
+    }
 }

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

@@ -28,6 +28,7 @@ class PythonBridge(private val context: Context) {
     // single-writer/single-reader pattern we have here.
     @Volatile private var mediaProjectionEngine: PyObject? = null
     @Volatile private var rootEngine: PyObject? = null
+    @Volatile private var androidAudioEngine: PyObject? = null
 
     /**
      * Configure the MediaProjection engine with screen dimensions.
@@ -53,6 +54,49 @@ class PythonBridge(private val context: Context) {
         Log.i(TAG, "Root screenrecord engine configured: ${width}x${height}")
     }
 
+    /**
+     * Configure the Android playback-capture audio engine with the format
+     * actually negotiated by [AudioCapture]'s `AudioRecord`. Must be called
+     * before [pushAudio]. Caches the module handle for the per-block fast
+     * path (same pattern as [configureCapture]).
+     */
+    fun configureAudio(sampleRate: Int, channels: Int, chunkFrames: Int) {
+        val py = Python.getInstance()
+        val engine = py.getModule("ledgrab.core.audio.android_audio_engine")
+        engine.callAttr("configure", sampleRate, channels, chunkFrames)
+        androidAudioEngine = engine
+        Log.i(TAG, "Android audio engine configured: sr=$sampleRate ch=$channels chunk=$chunkFrames")
+    }
+
+    /**
+     * Push one interleaved little-endian float32 PCM block to the Python
+     * audio engine. Called from [AudioCapture]'s capture thread. The byte
+     * array crosses the JNI boundary; Python copies it on receipt, so the
+     * caller may reuse the same buffer for the next block.
+     */
+    fun pushAudio(pcmFloat32: ByteArray) {
+        if (!running) return
+        val engine = androidAudioEngine ?: return
+        try {
+            engine.callAttr("push_samples", pcmFloat32)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to push audio: ${e.message}")
+        }
+    }
+
+    /**
+     * Deactivate the Python audio engine. Called from [AudioCapture.stop].
+     */
+    fun shutdownAudio() {
+        val engine = androidAudioEngine ?: return
+        try {
+            engine.callAttr("shutdown")
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to shut down audio engine: ${e.message}")
+        }
+        androidAudioEngine = null
+    }
+
     /**
      * Start the LedGrab FastAPI server on a background thread.
      *

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

@@ -66,6 +66,36 @@
             android:focusableInTouchMode="true"
             android:nextFocusDown="@+id/autostart_check" />
 
+        <!-- Shown only while notification-listener access is missing. The D-pad
+             focus chain is wired at runtime (wireStoppedFocusChain) because this
+             button and the autostart checkbox are both conditionally visible. -->
+        <Button
+            android:id="@+id/grant_notification_button"
+            style="@style/Widget.LedGrab.Button.Secondary"
+            android:layout_width="320dp"
+            android:layout_height="56dp"
+            android:layout_marginTop="20dp"
+            android:text="@string/btn_grant_notification_access"
+            android:textSize="18sp"
+            android:focusable="true"
+            android:focusableInTouchMode="true"
+            android:visibility="gone" />
+
+        <!-- Shown only while Usage Access is missing (needed by the foreground-app
+             automation rule). Like the grant-notification button, its D-pad focus
+             chain is wired at runtime (wireStoppedFocusChain). -->
+        <Button
+            android:id="@+id/grant_usage_access_button"
+            style="@style/Widget.LedGrab.Button.Secondary"
+            android:layout_width="320dp"
+            android:layout_height="56dp"
+            android:layout_marginTop="20dp"
+            android:text="@string/btn_grant_usage_access"
+            android:textSize="18sp"
+            android:focusable="true"
+            android:focusableInTouchMode="true"
+            android:visibility="gone" />
+
         <CheckBox
             android:id="@+id/autostart_check"
             android:layout_width="wrap_content"

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

@@ -25,4 +25,7 @@
     <string name="notification_channel_description">Отображается, пока LedGrab захватывает экран.</string>
     <string name="notification_title">LedGrab работает</string>
     <string name="notification_text">Веб-интерфейс: %1$s</string>
+    <string name="notification_listener_label">Захват уведомлений LedGrab</string>
+    <string name="btn_grant_notification_access">Разрешить доступ к уведомлениям</string>
+    <string name="btn_grant_usage_access">Разрешить доступ к статистике использования</string>
 </resources>

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

@@ -25,4 +25,7 @@
     <string name="notification_channel_description">LedGrab 捕获屏幕时显示。</string>
     <string name="notification_title">LedGrab 运行中</string>
     <string name="notification_text">Web界面:%1$s</string>
+    <string name="notification_listener_label">LedGrab 通知捕获</string>
+    <string name="btn_grant_notification_access">授予通知访问权限</string>
+    <string name="btn_grant_usage_access">授予使用情况访问权限</string>
 </resources>

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

@@ -25,4 +25,7 @@
     <string name="notification_channel_description">Shows while LedGrab is capturing the screen.</string>
     <string name="notification_title">LedGrab Running</string>
     <string name="notification_text">Web UI: %1$s</string>
+    <string name="notification_listener_label">LedGrab notification capture</string>
+    <string name="btn_grant_notification_access">Grant notification access</string>
+    <string name="btn_grant_usage_access">Grant usage access</string>
 </resources>

build/generate_icon.py

@@ -0,0 +1,327 @@
+"""Generate LedGrab app icon assets.
+
+Concept: "Spectrum Aperture" — a rounded-square frame (the screen/display)
+traced by a continuous RGB color-wheel stroke (the bias-light LED strip),
+on a near-black canvas with a soft chromatic bloom behind it.
+
+Outputs:
+    server/src/ledgrab/static/icons/icon-512.png           (standard, opaque vignette bg)
+    server/src/ledgrab/static/icons/icon-192.png           (downscale of 512)
+    server/src/ledgrab/static/icons/icon-512-maskable.png  (safe-area padded, opaque)
+    server/src/ledgrab/static/icons/icon-tray.png          (256, transparent bg, frame + glow)
+    server/src/ledgrab/static/icons/icon.ico               (16/24/32/48/64/128/256)
+
+Run from repo root:
+    py -3.13 build/generate_icon.py
+"""
+
+from __future__ import annotations
+
+import colorsys
+import math
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter
+
+# ── Tunables ────────────────────────────────────────────────────────────
+SUPERSAMPLE = 4  # render at 4x and downsample for crispness
+BASE = 1024  # logical canvas size
+HQ = BASE * SUPERSAMPLE  # render canvas
+
+BG_TOP = (12, 14, 22)  # near-black, faint cool tint
+BG_BOTTOM = (6, 7, 12)  # darker at edges (vignette feel)
+
+FRAME_INSET = 0.18  # margin from canvas edge to frame (fraction)
+FRAME_RADIUS = 0.22  # corner radius (fraction of frame side)
+FRAME_STROKE = 0.085  # stroke width (fraction of canvas)
+BLOOM_OPACITY = 0.62  # outer bloom strength (0–1)
+INNER_GLOW_OPACITY = 0.38  # inner chromatic reflection strength
+
+# Hue rotation offset so red sits at the top
+HUE_OFFSET = -90.0  # degrees (negative = counter-clockwise shift)
+
+
+def lerp(a: float, b: float, t: float) -> float:
+    return a + (b - a) * t
+
+
+def hue_to_rgb(hue_deg: float) -> tuple[int, int, int]:
+    """Bright, slightly desaturated spectral color (LED-like)."""
+    h = (hue_deg % 360) / 360.0
+    r, g, b = colorsys.hls_to_rgb(h, 0.58, 0.92)
+    return int(r * 255), int(g * 255), int(b * 255)
+
+
+def vignette_background(size: int) -> Image.Image:
+    """Dark canvas with a soft radial vignette + faint scanline noise."""
+    img = Image.new("RGB", (size, size), BG_TOP)
+    px = img.load()
+    cx, cy = size / 2, size / 2
+    max_r = math.hypot(cx, cy)
+    for y in range(size):
+        for x in range(size):
+            d = math.hypot(x - cx, y - cy) / max_r
+            t = min(1.0, d**1.6)
+            px[x, y] = (
+                int(lerp(BG_TOP[0], BG_BOTTOM[0], t)),
+                int(lerp(BG_TOP[1], BG_BOTTOM[1], t)),
+                int(lerp(BG_TOP[2], BG_BOTTOM[2], t)),
+            )
+    return img
+
+
+def draw_chromatic_bloom(size: int) -> Image.Image:
+    """Soft, large chromatic glow behind the frame — the bias-light effect."""
+    layer = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    cx, cy = size / 2, size / 2
+    radius = size * 0.36
+    blob_r = int(size * 0.30)
+    n_blobs = 24
+
+    for i in range(n_blobs):
+        a = i / n_blobs * 360.0
+        bx = cx + math.cos(math.radians(a - 90)) * radius
+        by = cy + math.sin(math.radians(a - 90)) * radius
+        r, g, b = hue_to_rgb(a + HUE_OFFSET)
+        alpha = int(255 * BLOOM_OPACITY * 0.55)
+        draw.ellipse(
+            (bx - blob_r, by - blob_r, bx + blob_r, by + blob_r),
+            fill=(r, g, b, alpha),
+        )
+
+    # Heavy blur → continuous, dreamy halo
+    layer = layer.filter(ImageFilter.GaussianBlur(radius=size * 0.10))
+    return layer
+
+
+def rounded_rect_mask(size: int, inset: int, radius: int, stroke: int) -> Image.Image:
+    """L-mode mask of a rounded-rect ring (the frame stroke region)."""
+    mask = Image.new("L", (size, size), 0)
+    draw = ImageDraw.Draw(mask)
+    box_outer = (inset, inset, size - inset, size - inset)
+    box_inner = (
+        inset + stroke,
+        inset + stroke,
+        size - inset - stroke,
+        size - inset - stroke,
+    )
+    r_outer = radius
+    r_inner = max(0, radius - stroke)
+    draw.rounded_rectangle(box_outer, radius=r_outer, fill=255)
+    draw.rounded_rectangle(box_inner, radius=r_inner, fill=0)
+    return mask
+
+
+def draw_spectrum_frame(size: int) -> Image.Image:
+    """Draw the rounded-square frame stroke filled with a hue-rotation gradient.
+
+    Strategy: paint a full-canvas angular hue gradient (centered), then
+    clip it with the rounded-ring mask. This guarantees a continuous,
+    seam-free color flow around the entire frame.
+    """
+    cx, cy = size / 2, size / 2
+
+    gradient = Image.new("RGB", (size, size), (0, 0, 0))
+    gpx = gradient.load()
+    for y in range(size):
+        dy = y - cy
+        for x in range(size):
+            dx = x - cx
+            ang = math.degrees(math.atan2(dy, dx)) + 90.0  # 0° = top
+            r, g, b = hue_to_rgb(ang + HUE_OFFSET)
+            gpx[x, y] = (r, g, b)
+
+    inset = int(size * FRAME_INSET)
+    frame_side = size - 2 * inset
+    stroke = int(size * FRAME_STROKE)
+    radius = int(frame_side * FRAME_RADIUS)
+
+    mask = rounded_rect_mask(size, inset, radius, stroke)
+
+    out = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    out.paste(gradient, (0, 0), mask)
+    return out
+
+
+def draw_inner_screen(size: int) -> Image.Image:
+    """Subtle dark rounded square inside the frame, with faint chromatic
+    inner reflection along the edges — like a screen catching ambient light."""
+    inset = int(size * FRAME_INSET)
+    stroke = int(size * FRAME_STROKE)
+    frame_side = size - 2 * inset
+    radius = int(frame_side * FRAME_RADIUS)
+
+    pad = int(stroke * 0.35)
+    box = (
+        inset + stroke + pad,
+        inset + stroke + pad,
+        size - inset - stroke - pad,
+        size - inset - stroke - pad,
+    )
+    r_inner = max(0, radius - stroke - pad)
+
+    layer = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+    # Dark fill, very slight cool tint
+    draw.rounded_rectangle(box, radius=r_inner, fill=(10, 12, 18, 255))
+
+    # Inner chromatic glow: same spectrum, very soft, clipped to the screen
+    bloom = draw_chromatic_bloom(size)
+    screen_mask = Image.new("L", (size, size), 0)
+    ImageDraw.Draw(screen_mask).rounded_rectangle(box, radius=r_inner, fill=255)
+
+    bloom_alpha = bloom.split()[-1].point(lambda v: int(v * INNER_GLOW_OPACITY))
+    bloom.putalpha(bloom_alpha)
+
+    masked_bloom = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    masked_bloom.paste(bloom, (0, 0), screen_mask)
+    layer.alpha_composite(masked_bloom)
+
+    # Faint highlight glint top-left
+    glint = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    gdraw = ImageDraw.Draw(glint)
+    glint_box = (
+        box[0] + int(frame_side * 0.04),
+        box[1] + int(frame_side * 0.04),
+        box[0] + int(frame_side * 0.42),
+        box[1] + int(frame_side * 0.18),
+    )
+    gdraw.rounded_rectangle(glint_box, radius=int(frame_side * 0.05), fill=(255, 255, 255, 22))
+    glint = glint.filter(ImageFilter.GaussianBlur(radius=size * 0.012))
+    masked_glint = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    masked_glint.paste(glint, (0, 0), screen_mask)
+    layer.alpha_composite(masked_glint)
+
+    return layer
+
+
+def add_outer_frame_glow(frame_rgba: Image.Image) -> Image.Image:
+    """Take the spectrum frame and produce a blurred, brightened copy for glow."""
+    glow = frame_rgba.copy()
+    # Slightly inflate brightness for glow
+    r, g, b, a = glow.split()
+    glow = Image.merge("RGBA", (r, g, b, a.point(lambda v: min(255, int(v * 0.85)))))
+    glow = glow.filter(ImageFilter.GaussianBlur(radius=glow.width * 0.025))
+    return glow
+
+
+def render_tray(size: int) -> Image.Image:
+    """Render a tray-optimised icon: transparent background, bolder frame,
+    tight outer glow. Designed to read clearly at 16–32 px on top of any
+    taskbar color."""
+    hq = size * SUPERSAMPLE
+
+    # Pull the frame inward a touch and beef up the stroke so it reads at 16 px.
+    global FRAME_INSET, FRAME_STROKE
+    saved_inset, saved_stroke = FRAME_INSET, FRAME_STROKE
+    FRAME_INSET = 0.13
+    FRAME_STROKE = 0.115
+    try:
+        frame = draw_spectrum_frame(hq)
+    finally:
+        FRAME_INSET, FRAME_STROKE = saved_inset, saved_stroke
+
+    # Tight, bright glow that doesn't bleed past the tray cell.
+    glow = frame.copy()
+    r, g, b, a = glow.split()
+    glow = Image.merge("RGBA", (r, g, b, a.point(lambda v: min(255, int(v * 0.95)))))
+    glow = glow.filter(ImageFilter.GaussianBlur(radius=hq * 0.012))
+
+    canvas = Image.new("RGBA", (hq, hq), (0, 0, 0, 0))
+    canvas.alpha_composite(glow)
+    canvas.alpha_composite(frame)
+
+    return canvas.resize((size, size), Image.LANCZOS)
+
+
+def render(size: int, *, maskable: bool = False) -> Image.Image:
+    """Render the full icon at the given size."""
+    hq = size * SUPERSAMPLE
+
+    if maskable:
+        # Maskable: pad inward so the entire icon survives a circular crop.
+        # We render the standard composition at 80% of canvas size, centered.
+        bg = Image.new("RGB", (hq, hq), BG_BOTTOM).convert("RGBA")
+        bg.paste(vignette_background(hq), (0, 0))
+
+        inner = render(size, maskable=False).resize((int(hq * 0.78), int(hq * 0.78)), Image.LANCZOS)
+        # Strip the bg from the inner render: composite the spectrum
+        # parts on top of our maskable background.
+        ox = (hq - inner.width) // 2
+        oy = (hq - inner.height) // 2
+        bg.alpha_composite(inner, (ox, oy))
+        return bg.resize((size, size), Image.LANCZOS)
+
+    bg = vignette_background(hq).convert("RGBA")
+    bloom = draw_chromatic_bloom(hq)
+    frame = draw_spectrum_frame(hq)
+    frame_glow = add_outer_frame_glow(frame)
+    inner_screen = draw_inner_screen(hq)
+
+    # Composite order: bg → bloom → frame_glow → inner_screen → frame
+    canvas = Image.new("RGBA", (hq, hq), (0, 0, 0, 0))
+    canvas.alpha_composite(bg)
+    canvas.alpha_composite(bloom)
+    canvas.alpha_composite(frame_glow)
+    canvas.alpha_composite(inner_screen)
+    canvas.alpha_composite(frame)
+
+    return canvas.resize((size, size), Image.LANCZOS)
+
+
+def main() -> None:
+    repo_root = Path(__file__).resolve().parent.parent
+    targets = [
+        repo_root / "server" / "src" / "ledgrab" / "static" / "icons",
+        repo_root
+        / "android"
+        / "app"
+        / "build"
+        / "python"
+        / "sources"
+        / "debug"
+        / "ledgrab"
+        / "static"
+        / "icons",
+    ]
+
+    print("Rendering 1024 master...")
+    master = render(1024, maskable=False)
+
+    print("Rendering maskable 1024 master...")
+    maskable_master = render(1024, maskable=True)
+
+    print("Rendering tray 512 master (transparent bg)...")
+    tray_master = render_tray(512)
+
+    for icons_dir in targets:
+        if not icons_dir.exists():
+            print(f"  skip (missing): {icons_dir}")
+            continue
+
+        out_512 = icons_dir / "icon-512.png"
+        out_192 = icons_dir / "icon-192.png"
+        out_mask = icons_dir / "icon-512-maskable.png"
+        out_tray = icons_dir / "icon-tray.png"
+        out_ico = icons_dir / "icon.ico"
+
+        master.resize((512, 512), Image.LANCZOS).save(out_512, "PNG", optimize=True)
+        master.resize((192, 192), Image.LANCZOS).save(out_192, "PNG", optimize=True)
+        maskable_master.resize((512, 512), Image.LANCZOS).save(out_mask, "PNG", optimize=True)
+        tray_master.save(out_tray, "PNG", optimize=True)
+
+        # Pre-resize each frame from the 1024 master for maximum crispness.
+        # Pass them via the `sizes` arg so Pillow embeds every variant.
+        ico_sizes = [(16, 16), (24, 24), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)]
+        # Use the tray (transparent-bg) variant for ICO frames so the file/
+        # taskbar icon doesn't show a dark tile against light backgrounds.
+        ico_source = tray_master.resize((256, 256), Image.LANCZOS)
+        ico_source.save(out_ico, format="ICO", sizes=ico_sizes)
+
+        print(f"  wrote: {icons_dir}")
+
+
+if __name__ == "__main__":
+    main()

build/installer.nsi

@@ -56,9 +56,10 @@ SetCompressor /SOLID lzma
 ; ── Functions ─────────────────────────────────────────────
 
 Function LaunchApp
+  ; Only launch the app — do NOT open the browser here. A manual launch (no
+  ; --autostart) makes the app open the WebUI itself once /health responds,
+  ; so opening the URL here too made the page appear twice.
   ExecShell "open" "wscript.exe" '"$INSTDIR\scripts\${VBSNAME}"'
-  Sleep 2000
-  ExecShell "open" "http://localhost:8080/"
 FunctionEnd
 
 ; Detect running instance before install (file lock check on python.exe)

docs/API.md

@@ -1,335 +1,651 @@
-# LedGrab API Documentation
+# LedGrab API Reference
 
-Complete REST API reference for the LedGrab server.
+Complete REST + WebSocket API reference for the LedGrab server.
 
-**Base URL:** `http://localhost:8080`
+- **Base URL:** `http://localhost:8080`
-**API Version:** v1
+- **API version:** `v1` (all REST paths are under `/api/v1`, except `/health`)
+- **Interactive docs:** Swagger UI at [`/docs`](http://localhost:8080/docs), ReDoc at [`/redoc`](http://localhost:8080/redoc), raw schema at [`/openapi.json`](http://localhost:8080/openapi.json). The interactive docs are always the authoritative, up-to-date source for request/response schemas — this file is a hand-maintained overview.
+
+> The application version is reported by `GET /api/v1/version`; this document is version-agnostic.
 
 ---
 
 ## Table of Contents
 
-- [Health & Info](#health--info)
+- [Authentication](#authentication)
-- [Device Management](#device-management)
+- [Conventions](#conventions)
-- [Processing Control](#processing-control)
+- [WebSocket protocol](#websocket-protocol)
-- [Settings Management](#settings-management)
+- [Worked examples](#worked-examples)
-- [Calibration](#calibration)
+- **Endpoint reference**
-- [Metrics](#metrics)
+  - [Health & system info](#health--system-info)
+  - [System settings](#system-settings)
+  - [User preferences](#user-preferences)
+  - [Backup, restore & server control](#backup-restore--server-control)
+  - [Updates](#updates)
+  - [Snapshot](#snapshot)
+  - [Devices](#devices)
+  - [Capture templates, engines & filters](#capture-templates-engines--filters)
+  - [Picture sources](#picture-sources)
+  - [Post-processing templates](#post-processing-templates)
+  - [Output targets](#output-targets)
+  - [Output target control & live preview](#output-target-control--live-preview)
+  - [Color strip sources](#color-strip-sources)
+  - [Color strip processing templates](#color-strip-processing-templates)
+  - [Pattern templates](#pattern-templates)
+  - [Gradients](#gradients)
+  - [Audio devices](#audio-devices)
+  - [Audio sources](#audio-sources)
+  - [Audio templates & engines](#audio-templates--engines)
+  - [Audio processing templates](#audio-processing-templates)
+  - [Audio filters](#audio-filters)
+  - [Value sources](#value-sources)
+  - [Weather sources](#weather-sources)
+  - [Automations](#automations)
+  - [Scene presets](#scene-presets)
+  - [Sync clocks](#sync-clocks)
+  - [Webhooks](#webhooks)
+  - [HTTP endpoints](#http-endpoints)
+  - [Game integration](#game-integration)
+  - [Home Assistant](#home-assistant)
+  - [MQTT sources](#mqtt-sources)
+  - [Assets](#assets)
+  - [Graph wiring](#graph-wiring)
+  - [Web UI & PWA](#web-ui--pwa)
 
 ---
 
-## Health & Info
+## Authentication
 
-### GET /health
+LedGrab uses API-key authentication. The behavior depends on whether any keys are configured under `auth.api_keys` (see [INSTALLATION.md](../INSTALLATION.md)):
 
-Health check endpoint.
+| Situation | Loopback (`127.0.0.1` / `::1` / `localhost`) | LAN / remote |
+| --------- | -------------------------------------------- | ------------ |
+| **No keys configured** (default) | Allowed anonymously | **Rejected with `401`** |
+| **Keys configured** | Valid Bearer token required | Valid Bearer token required |
+
+Pass the key as a Bearer token:
+
+```http
+Authorization: Bearer <your-api-key>
+```
+
+A few **sensitive endpoints require a real API key even from localhost** (they reject the loopback-anonymous identity): the backup download/restore endpoints, and any endpoint that reveals stored secrets (e.g. `GET /api/v1/home-assistant/sources?include_secrets=true`). Configure a key to use those.
+
+WebSocket endpoints authenticate with a [first-message handshake](#websocket-protocol) rather than the `Authorization` header.
+
+---
+
+## Conventions
+
+- **Content type:** request and response bodies are JSON (`application/json`) unless noted (file uploads use `multipart/form-data`; some endpoints stream binary or file responses).
+- **Errors:** failures return the standard FastAPI shape with an HTTP status code and a body of `{"detail": "<message>"}`. Validation errors return `422` with a structured `detail` array.
+- **IDs:** entities are addressed by string IDs (e.g. `dev_…`, `ot_…`, `css_…`) generated on creation.
+- **Common create/update fields:** most configurable entities accept `name`, `description`, `tags` (string array), and UI styling fields `icon` and `icon_color`.
+- **Referential integrity:** deleting an entity that is still referenced (e.g. a device used by an output target) returns `409 Conflict`.
+- **Timestamps:** ISO-8601 UTC strings.
+
+---
+
+## WebSocket protocol
+
+All WebSocket endpoints share the same auth handshake:
+
+1. The client connects. The server accepts the socket.
+2. The client sends a JSON auth message as the **first** message, within ~3 seconds: `{"type": "auth", "token": "<your-api-key>"}`. On loopback with no keys configured, `token` may be `null` or the message omitted.
+3. The server replies `{"type": "auth_ok"}` on success, or `{"type": "auth_error", "reason": "..."}` then closes (close code `4401`) on failure. A cross-site `Origin` is rejected with close code `4403`.
+
+Browser clients must connect from an allowed `cors_origins` origin. After `auth_ok`, the stream payload depends on the endpoint (JSON event objects, JSON spectrum/metric frames, or binary RGB frames — see each endpoint's description).
+
+The WebSocket endpoints are listed within their resource sections below (method `WS`).
+
+---
+
+## Worked examples
+
+> Example values are illustrative.
+
+**Health check** — `GET /health` (no auth on loopback):
 
-**Response:**
 ```json
 {
   "status": "healthy",
-  "timestamp": "2026-02-06T12:00:00Z",
+  "timestamp": "2026-05-29T12:00:00Z",
-  "version": "0.1.0"
+  "version": "0.8.1",
+  "demo_mode": false,
+  "auth_required": false,
+  "setup_required": false,
+  "uptime_seconds": 3600
 }
 ```
 
-### GET /api/v1/version
+**Create a WLED device** — `POST /api/v1/devices`:
 
-Get version information.
-
-**Response:**
-```json
-{
-  "version": "0.1.0",
-  "python_version": "3.11.0",
-  "api_version": "v1"
-}
-```
-
-### GET /api/v1/config/displays
-
-List available displays for screen capture.
-
-**Response:**
-```json
-{
-  "displays": [
-    {
-      "index": 0,
-      "name": "Display 1",
-      "width": 1920,
-      "height": 1080,
-      "is_primary": true
-    }
-  ],
-  "count": 1
-}
-```
-
----
-
-## Device Management
-
-### POST /api/v1/devices
-
-Create and attach a new WLED device.
-
-**Request:**
 ```json
 {
   "name": "Living Room TV",
   "url": "http://192.168.1.100",
+  "device_type": "wled",
   "led_count": 150
 }
 ```
 
-**Response:** `201 Created`
+Response `201 Created` returns the stored device, including its generated `id`. (For Adalight, send `device_type: "adalight"`, the serial `url` like `COM3` or `/dev/ttyUSB0`, `led_count`, and `baud_rate`. Each device type accepts its own fields — see `/docs`.)
+
+**Start / stop a target** — `POST /api/v1/output-targets/{target_id}/start`:
+
 ```json
-{
+{ "status": "started", "target_id": "ot_abc123" }
-  "id": "device_abc123",
-  "name": "Living Room TV",
-  "url": "http://192.168.1.100",
-  "led_count": 150,
-  "enabled": true,
-  "status": "disconnected",
-  "settings": {
-    "display_index": 0,
-    "fps": 30,
-    "border_width": 10
-  },
-  "calibration": {
-    "layout": "clockwise",
-    "start_position": "bottom_left",
-    "segments": [...]
-  },
-  "created_at": "2026-02-06T12:00:00Z",
-  "updated_at": "2026-02-06T12:00:00Z"
-}
 ```
 
-### GET /api/v1/devices
+**Authenticated request with a configured key:**
 
-List all attached devices.
+```bash
-
+curl -H "Authorization: Bearer your-api-key" \
-**Response:**
+  http://localhost:8080/api/v1/devices
-```json
-{
-  "devices": [...],
-  "count": 2
-}
-```
-
-### GET /api/v1/devices/{device_id}
-
-Get device details.
-
-**Response:** Same as POST response
-
-### PUT /api/v1/devices/{device_id}
-
-Update device information.
-
-**Request:**
-```json
-{
-  "name": "Updated Name",
-  "enabled": true
-}
-```
-
-### DELETE /api/v1/devices/{device_id}
-
-Delete/detach a device.
-
-**Response:** `204 No Content`
-
----
-
-## Processing Control
-
-### POST /api/v1/devices/{device_id}/start
-
-Start screen processing for a device.
-
-**Response:**
-```json
-{
-  "status": "started",
-  "device_id": "device_abc123"
-}
-```
-
-### POST /api/v1/devices/{device_id}/stop
-
-Stop screen processing.
-
-**Response:**
-```json
-{
-  "status": "stopped",
-  "device_id": "device_abc123"
-}
-```
-
-### GET /api/v1/devices/{device_id}/state
-
-Get current processing state.
-
-**Response:**
-```json
-{
-  "device_id": "device_abc123",
-  "processing": true,
-  "fps_actual": 29.8,
-  "fps_target": 30,
-  "display_index": 0,
-  "last_update": "2026-02-06T12:00:00Z",
-  "errors": []
-}
 ```
 
 ---
 
-## Settings Management
+## Endpoint reference
 
-### GET /api/v1/devices/{device_id}/settings
+## Health & system info
 
-Get processing settings.
+Health checks, version information, displays, system metrics, and integration status.
 
-**Response:**
+| Method | Path | Description |
-```json
+| ------ | ---- | ----------- |
-{
+| GET | `/health` | Service health: status, version, uptime, and whether auth/setup is required. |
-  "display_index": 0,
+| GET | `/api/v1/version` | Application version, Python version, and API version. |
-  "fps": 30,
+| GET | `/api/v1/tags` | All tags used across every entity in the system. |
-  "brightness": 1.0,
+| GET | `/api/v1/config/displays` | Available displays/monitors for screen capture (optional `engine_type` query, e.g. `scrcpy`). |
-  "smoothing": 0.3,
+| GET | `/api/v1/system/processes` | Running process names, for use in automation conditions. |
-  "interpolation_mode": "average",
+| GET | `/api/v1/system/performance` | Current CPU, RAM, and GPU utilization metrics. |
-  "standby_interval": 1.0,
+| GET | `/api/v1/system/metrics-history` | Last ~2 minutes of system and per-target metrics for dashboard charts. |
-  "state_check_interval": 30
+| GET | `/api/v1/system/api-keys` | API-key labels with masked values (read-only; keys live in YAML config). |
-}
+| GET | `/api/v1/system/integrations-status` | Connection status for MQTT and Home Assistant integrations. |
-```
 
-### PUT /api/v1/devices/{device_id}/settings
+## System settings
 
-Update processing settings.
+Server configuration: MQTT broker, external URL, shutdown action, log level, ADB connection, and live log streaming.
 
-**Request:**
+| Method | Path | Description |
-```json
+| ------ | ---- | ----------- |
-{
+| GET | `/api/v1/system/mqtt/settings` | Current MQTT broker settings (password masked). |
-  "display_index": 1,
+| PUT | `/api/v1/system/mqtt/settings` | Update MQTT broker settings (empty password preserves existing). |
-  "fps": 60,
+| GET | `/api/v1/system/external-url` | Configured external base URL. |
-  "brightness": 0.8
+| PUT | `/api/v1/system/external-url` | Set the external base URL for webhooks and user-visible links. |
-}
+| GET | `/api/v1/system/shutdown-action` | Configured server shutdown action (`stop_targets` or `nothing`). |
-```
+| PUT | `/api/v1/system/shutdown-action` | Set what happens to targets when the server shuts down. |
+| WS | `/api/v1/system/logs/ws` | Live server log stream with a buffered backlog. |
+| POST | `/api/v1/adb/connect` | Connect to a Wi-Fi ADB device by IP (auto-appends `:5555`). |
+| POST | `/api/v1/adb/disconnect` | Disconnect a Wi-Fi ADB device. |
+| GET | `/api/v1/system/log-level` | Current root logger level. |
+| PUT | `/api/v1/system/log-level` | Change the log level at runtime without restart. |
+
+## User preferences
+
+Dashboard layout, notification settings, card display modes, and the global daylight timezone.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/preferences/dashboard-layout` | Read the saved dashboard layout (empty when unset). |
+| PUT | `/api/v1/preferences/dashboard-layout` | Save the dashboard layout (opaque versioned JSON blob). |
+| DELETE | `/api/v1/preferences/dashboard-layout` | Delete the saved layout; revert to default. |
+| GET | `/api/v1/preferences/notifications` | Read notification preferences (server defaults when unset). |
+| PUT | `/api/v1/preferences/notifications` | Persist notification preferences (channels, discovery, grace/debounce). |
+| GET | `/api/v1/preferences/card-modes` | Read per-surface card-mode preferences. |
+| PUT | `/api/v1/preferences/card-modes` | Save per-surface card modes (comfortable/compact/dense/row). |
+| DELETE | `/api/v1/preferences/card-modes` | Delete card-mode preferences; revert to defaults. |
+| GET | `/api/v1/preferences/daylight-timezone` | Read the global IANA timezone for daylight cycles. |
+| PUT | `/api/v1/preferences/daylight-timezone` | Persist the daylight-cycle timezone (empty = server local). |
+
+## Backup, restore & server control
+
+Database backup/restore, server restart/shutdown, and auto-backup management.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/system/backup` | Download a full backup `.zip` (database + assets). 🔒 requires a key. |
+| POST | `/api/v1/system/restore` | Upload a `.db`/`.zip` backup to restore config and trigger a restart. 🔒 requires a key. |
+| POST | `/api/v1/system/restart` | Schedule a server restart and return immediately. |
+| POST | `/api/v1/system/shutdown` | Gracefully shut down the server. |
+| GET | `/api/v1/system/auto-backup/settings` | Auto-backup settings and status (enabled, interval, retention, last/next). |
+| PUT | `/api/v1/system/auto-backup/settings` | Update auto-backup settings. |
+| POST | `/api/v1/system/auto-backup/trigger` | Trigger a backup now and return its metadata. |
+| GET | `/api/v1/system/backups` | List saved auto-backup files. |
+| GET | `/api/v1/system/backups/{filename}` | Download a specific saved backup file. |
+| DELETE | `/api/v1/system/backups/{filename}` | Delete a specific saved backup file. |
+
+> 🔒 = requires a real API key even from localhost (rejects loopback-anonymous access).
+
+## Updates
+
+Auto-update management: check, apply, dismiss, and configure.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/system/update/status` | Current update status (available version, install type, capability). |
+| POST | `/api/v1/system/update/check` | Trigger an immediate update check. |
+| POST | `/api/v1/system/update/dismiss` | Dismiss the notification for a specific version. |
+| POST | `/api/v1/system/update/apply` | Download and apply the available update, then shut down. |
+| GET | `/api/v1/system/update/settings` | Update settings (enabled, interval, include prereleases). |
+| PUT | `/api/v1/system/update/settings` | Change auto-update settings. |
+
+## Snapshot
+
+A single aggregated poll endpoint for low-overhead clients.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/snapshot` | Full poll payload (targets, states, metrics, devices, brightness, color/value sources, scene presets, sync clocks, system) in one response. Use `?include=` to request a subset; per-section fault isolation. |
+
+## Devices
+
+LED device CRUD, pairing, discovery, health checks, brightness/power control, and the WS pixel stream.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/devices` | Create/attach a new LED device (validates connectivity). |
+| POST | `/api/v1/devices/pair` | Run a pairing handshake before creating a device. |
+| GET | `/api/v1/devices` | List all attached devices. |
+| GET | `/api/v1/devices/discover` | Scan the network for devices (optional `timeout`, `device_type`). |
+| GET | `/api/v1/devices/openrgb-zones` | List zones on an OpenRGB device (`url` query). |
+| GET | `/api/v1/devices/batch/states` | Health/connection state for all devices at once. |
+| GET | `/api/v1/devices/{device_id}` | Get a device by ID. |
+| PUT | `/api/v1/devices/{device_id}` | Update device configuration. |
+| DELETE | `/api/v1/devices/{device_id}` | Delete/detach a device (`409` if referenced). |
+| GET | `/api/v1/devices/{device_id}/state` | Get device health/connection state. |
+| POST | `/api/v1/devices/{device_id}/ping` | Force an immediate health check. |
+| GET | `/api/v1/devices/{device_id}/brightness` | Get current (cached) brightness. |
+| PUT | `/api/v1/devices/{device_id}/brightness` | Set brightness (`0–255`). |
+| GET | `/api/v1/devices/{device_id}/power` | Get current power state. |
+| PUT | `/api/v1/devices/{device_id}/power` | Turn the device on or off. |
+| WS | `/api/v1/devices/{device_id}/ws` | Pixel stream for `ws` device type (`[brightness][R G B …]`). |
+
+## Capture templates, engines & filters
+
+Capture template CRUD/testing, capture engine discovery, and post-processing filter discovery.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/capture-templates` | List all capture templates. |
+| POST | `/api/v1/capture-templates` | Create a capture template. |
+| GET | `/api/v1/capture-templates/{template_id}` | Get a capture template by ID. |
+| PUT | `/api/v1/capture-templates/{template_id}` | Update a capture template (partial). |
+| DELETE | `/api/v1/capture-templates/{template_id}` | Delete a template (`409` if used by streams). |
+| GET | `/api/v1/capture-engines` | List capture engines with platform availability. |
+| POST | `/api/v1/capture-templates/test` | Test a capture config; returns FPS metrics + preview. |
+| WS | `/api/v1/capture-templates/test/ws` | Real-time capture test with intermediate frame previews. |
+| GET | `/api/v1/filters` | List post-processing filter types and option schemas. |
+| GET | `/api/v1/strip-filters` | List filter types that support 1D LED-strip processing. |
+
+## Picture sources
+
+Screen captures, static images, video files, and processed streams used for color extraction.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/picture-sources` | List all picture sources. |
+| POST | `/api/v1/picture-sources/validate-image` | Validate an image source and return a preview thumbnail. |
+| GET | `/api/v1/picture-sources/full-image` | Serve a full-resolution image for lightbox preview (`source` query). |
+| POST | `/api/v1/picture-sources` | Create a picture source (`raw`/`processed`/`static`/`video`). |
+| GET | `/api/v1/picture-sources/{stream_id}` | Get a picture source by ID. |
+| PUT | `/api/v1/picture-sources/{stream_id}` | Update a picture source. |
+| DELETE | `/api/v1/picture-sources/{stream_id}` | Delete a picture source (`409` if referenced). |
+| GET | `/api/v1/picture-sources/{stream_id}/thumbnail` | Thumbnail (first frame) for a video source. |
+| POST | `/api/v1/picture-sources/{stream_id}/test` | Resolve the chain and run a capture test. |
+| WS | `/api/v1/picture-sources/{stream_id}/test/ws` | Test stream with intermediate frame previews. |
+
+## Post-processing templates
+
+Reusable filter chains applied to picture sources.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/postprocessing-templates` | List all post-processing templates. |
+| POST | `/api/v1/postprocessing-templates` | Create a template (name + filter list). |
+| GET | `/api/v1/postprocessing-templates/{template_id}` | Get a template by ID. |
+| PUT | `/api/v1/postprocessing-templates/{template_id}` | Update a template (partial). |
+| DELETE | `/api/v1/postprocessing-templates/{template_id}` | Delete a template (`409` if referenced). |
+| POST | `/api/v1/postprocessing-templates/{template_id}/test` | Capture from a source and apply the filters. |
+| WS | `/api/v1/postprocessing-templates/{template_id}/test/ws` | Real-time test with intermediate frame previews. |
+
+## Output targets
+
+LED strips, Home Assistant light groups, and Zigbee2MQTT bulb groups.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/output-targets` | Create a target (`led` / `ha_light` / `z2m_light`). |
+| GET | `/api/v1/output-targets` | List all output targets. |
+| GET | `/api/v1/output-targets/batch/states` | Processing state for all targets at once. |
+| GET | `/api/v1/output-targets/batch/metrics` | Metrics for all targets at once. |
+| GET | `/api/v1/output-targets/{target_id}` | Get a single target. |
+| PUT | `/api/v1/output-targets/{target_id}` | Update a target (partial, per type). |
+| DELETE | `/api/v1/output-targets/{target_id}` | Delete a target (stops processing first). |
+
+## Output target control & live preview
+
+Start/stop processing, state & metrics, the calibration overlay, the global event stream, and live color/LED preview WebSockets.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/output-targets/bulk/start` | Start processing for multiple targets. |
+| POST | `/api/v1/output-targets/bulk/stop` | Stop processing for multiple targets. |
+| POST | `/api/v1/output-targets/{target_id}/start` | Start processing for one target. |
+| POST | `/api/v1/output-targets/{target_id}/stop` | Stop processing for one target. |
+| GET | `/api/v1/output-targets/{target_id}/state` | Current processing state (FPS, timing, device, errors). |
+| GET | `/api/v1/output-targets/{target_id}/metrics` | Processing metrics (uptime, frames, error count). |
+| WS | `/api/v1/events/ws` | Real-time state-change events across all targets. |
+| POST | `/api/v1/output-targets/{target_id}/overlay/start` | Start the on-screen sampling/LED overlay. |
+| POST | `/api/v1/output-targets/{target_id}/overlay/stop` | Stop the overlay. |
+| GET | `/api/v1/output-targets/{target_id}/overlay/status` | Whether the overlay is active. |
+| POST | `/api/v1/output-targets/{target_id}/ha-light/turn-off` | Turn off all HA light entities for the target. |
+| WS | `/api/v1/output-targets/{target_id}/ha-light/ws` | Live HA light color preview. |
+| POST | `/api/v1/output-targets/{target_id}/z2m-light/turn-off` | Publish OFF to all Zigbee2MQTT bulbs for the target. |
+| WS | `/api/v1/output-targets/{target_id}/z2m-light/ws` | Live Zigbee2MQTT bulb color preview. |
+| WS | `/api/v1/output-targets/{target_id}/led-preview/ws` | Live LED-strip preview (binary RGB frames). |
+
+## Color strip sources
+
+CRUD, calibration, raw color push, notifications, and preview streaming for color strip sources.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/color-strip-sources` | List all color strip sources. |
+| POST | `/api/v1/color-strip-sources` | Create a color strip source (by `source_type`). |
+| GET | `/api/v1/color-strip-sources/{source_id}` | Get a color strip source by ID. |
+| PUT | `/api/v1/color-strip-sources/{source_id}` | Update a source; hot-reloads running streams. |
+| DELETE | `/api/v1/color-strip-sources/{source_id}` | Delete a source (`409` if referenced). |
+| POST | `/api/v1/color-strip-sources/{source_id}/overlay/start` | Start the screen overlay (picture-type, calibrated). |
+| POST | `/api/v1/color-strip-sources/{source_id}/overlay/stop` | Stop the screen overlay. |
+| GET | `/api/v1/color-strip-sources/{source_id}/overlay/status` | Whether the overlay is active. |
+| POST | `/api/v1/color-strip-sources/{source_id}/colors` | Push raw LED colors to an `api_input` source. |
+| POST | `/api/v1/color-strip-sources/{source_id}/notify` | Trigger a one-shot notification effect. |
+| GET | `/api/v1/color-strip-sources/os-notifications/history` | Recent OS-notification capture history. |
+| PUT | `/api/v1/color-strip-sources/{source_id}/calibration/test` | Light up LED edges to verify calibration. |
+| POST | `/api/v1/color-strip-sources/{source_id}/key-colors/test` | Test a `key_colors` source (extract colors from rectangles). |
+| WS | `/api/v1/color-strip-sources/{source_id}/key-colors/test/ws` | Real-time key-colors test preview. |
+| WS | `/api/v1/color-strip-sources/preview/ws` | Transient ad-hoc source preview stream. |
+| WS | `/api/v1/color-strip-sources/{source_id}/ws` | Push raw colors to an `api_input` source over WS. |
+| WS | `/api/v1/color-strip-sources/{source_id}/test/ws` | Real-time source preview (binary RGB, optional JPEG). |
+
+## Color strip processing templates
+
+Reusable filter chains applied to color strips (1D LED data).
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/color-strip-processing-templates` | List all color-strip processing templates. |
+| POST | `/api/v1/color-strip-processing-templates` | Create a template (name + filter list). |
+| GET | `/api/v1/color-strip-processing-templates/{template_id}` | Get a template by ID. |
+| PUT | `/api/v1/color-strip-processing-templates/{template_id}` | Update a template. |
+| DELETE | `/api/v1/color-strip-processing-templates/{template_id}` | Delete a template (`409` if referenced). |
+| WS | `/api/v1/color-strip-processing-templates/{template_id}/test/ws` | Real-time preview: apply the filter chain to an input source. |
+
+## Pattern templates
+
+Layout templates of named rectangles for LED device configuration.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/pattern-templates` | List all pattern templates. |
+| POST | `/api/v1/pattern-templates` | Create a pattern template (named rectangles). |
+| GET | `/api/v1/pattern-templates/{template_id}` | Get a pattern template by ID. |
+| PUT | `/api/v1/pattern-templates/{template_id}` | Update a pattern template. |
+| DELETE | `/api/v1/pattern-templates/{template_id}` | Delete a template (`409` if referenced by targets). |
+
+## Gradients
+
+Reusable gradient definitions (color stops). Built-in gradients are read-only but clonable.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/gradients` | List all gradients (built-in and user-created). |
+| POST | `/api/v1/gradients` | Create a user-defined gradient. |
+| GET | `/api/v1/gradients/{gradient_id}` | Get a gradient by ID. |
+| PUT | `/api/v1/gradients/{gradient_id}` | Update a gradient (built-ins are read-only). |
+| POST | `/api/v1/gradients/{gradient_id}/clone` | Clone a gradient into a customizable copy. |
+| DELETE | `/api/v1/gradients/{gradient_id}` | Delete a gradient (`400` if built-in or referenced). |
+
+## Audio devices
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/audio-devices` | List audio input/output devices (flat list + per-engine grouping). |
+
+## Audio sources
+
+Audio capture and processing sources for audio-reactive effects.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/audio-sources` | List all audio sources (optional `source_type`). |
+| POST | `/api/v1/audio-sources` | Create an audio source (`capture` or `processed`). |
+| GET | `/api/v1/audio-sources/{source_id}` | Get an audio source by ID. |
+| PUT | `/api/v1/audio-sources/{source_id}` | Update an audio source (partial). |
+| DELETE | `/api/v1/audio-sources/{source_id}` | Delete an audio source (`409` if referenced). |
+| WS | `/api/v1/audio-sources/{source_id}/test/ws` | Real-time spectrum/RMS/peak/beat analysis (~20 Hz). |
+
+## Audio templates & engines
+
+Audio capture templates and engine discovery.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/audio-templates` | List all audio capture templates. |
+| POST | `/api/v1/audio-templates` | Create an audio capture template. |
+| GET | `/api/v1/audio-templates/{template_id}` | Get an audio template by ID. |
+| PUT | `/api/v1/audio-templates/{template_id}` | Update an audio template. |
+| DELETE | `/api/v1/audio-templates/{template_id}` | Delete a template (cascades to audio sources). |
+| GET | `/api/v1/audio-engines` | List audio capture engines and availability. |
+| WS | `/api/v1/audio-templates/{template_id}/test/ws` | Real-time spectrum test for a template + device. |
+
+## Audio processing templates
+
+Reusable audio filter chains.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/audio-processing-templates` | List all audio processing templates. |
+| POST | `/api/v1/audio-processing-templates` | Create a template (name + filter list). |
+| GET | `/api/v1/audio-processing-templates/{template_id}` | Get a template by ID. |
+| PUT | `/api/v1/audio-processing-templates/{template_id}` | Update a template (hot-updates running streams). |
+| DELETE | `/api/v1/audio-processing-templates/{template_id}` | Delete a template (`409` if referenced). |
+
+## Audio filters
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/audio-filters` | List audio filter types and their option schemas. |
+
+## Value sources
+
+Dynamic data inputs (brightness and other parameters): static, animated, audio, adaptive, color, sensor, HTTP, Home Assistant, and `template` — a sandboxed-Jinja **combinator** that evaluates an expression over the live values of other value sources.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/value-sources` | List all value sources (optional `source_type`). |
+| POST | `/api/v1/value-sources` | Create a value source (discriminated by `source_type`). |
+| POST | `/api/v1/value-sources/validate-template` | Validate a template expression + inputs (advisory; always `200` with `{valid, error, errors, warnings, variables}`). |
+| GET | `/api/v1/value-sources/{source_id}` | Get a value source by ID. |
+| PUT | `/api/v1/value-sources/{source_id}` | Update a value source; hot-reloads running streams. |
+| DELETE | `/api/v1/value-sources/{source_id}` | Delete a value source (`400` if referenced by a target or another value source). |
+| WS | `/api/v1/value-sources/{source_id}/test/ws` | Real-time value output stream (~20 Hz). |
+
+### Template value source (`source_type: "template"`)
+
+A `float` combinator. Fields: `template` (a Jinja *expression*), `inputs` (`[{name, value_source_id}]` bindings to other value sources), `default_value` (fallback in `[0,1]` on any error), and `eval_interval` (optional re-eval throttle in seconds; `0`/null = every poll). At runtime each input is exposed by its `name` (the source's normalized `0..1` value) plus `raw[name]` (its un-normalized value, where available). Globals: `min`, `max`, `abs`, `round`, `clamp(x, lo=0, hi=1)`. The expression runs in a hardened `ImmutableSandboxedEnvironment` (no statements/blocks, filters, attribute access, `**`, or string repetition); results are coerced, NaN/inf-rejected, and clamped to `[0,1]`. Reference cycles and over-deep nesting are rejected at save time. For time-of-day logic, bind an `adaptive_time` or `daylight` source as an input.
+
+## Weather sources
+
+Weather data providers feeding weather-driven value sources.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/weather-sources` | List all weather sources. |
+| POST | `/api/v1/weather-sources` | Create a weather source (provider, lat/lon, interval). |
+| GET | `/api/v1/weather-sources/{source_id}` | Get a weather source by ID. |
+| PUT | `/api/v1/weather-sources/{source_id}` | Update a weather source. |
+| DELETE | `/api/v1/weather-sources/{source_id}` | Delete a weather source. |
+| POST | `/api/v1/weather-sources/{source_id}/test` | Force-fetch current weather and return it. |
+
+## Automations
+
+Rules that trigger scene presets (time, display state, MQTT, webhooks, Home Assistant, HTTP polling, active window).
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/automations` | Create an automation (rules + scene preset + deactivation). |
+| GET | `/api/v1/automations` | List automations with current activity state. |
+| GET | `/api/v1/automations/{automation_id}` | Get an automation by ID (includes webhook URL if any). |
+| PUT | `/api/v1/automations/{automation_id}` | Update an automation (partial); re-evaluates if enabled. |
+| DELETE | `/api/v1/automations/{automation_id}` | Delete and deactivate an automation. |
+| POST | `/api/v1/automations/{automation_id}/enable` | Enable and immediately evaluate rules. |
+| POST | `/api/v1/automations/{automation_id}/disable` | Disable and deactivate. |
+
+## Scene presets
+
+Captured snapshots of target state that can be restored.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/scene-presets` | Create a preset by capturing current target state. |
+| GET | `/api/v1/scene-presets` | List all scene presets. |
+| GET | `/api/v1/scene-presets/{preset_id}` | Get a scene preset by ID. |
+| PUT | `/api/v1/scene-presets/{preset_id}` | Update metadata and optionally change targets. |
+| DELETE | `/api/v1/scene-presets/{preset_id}` | Delete a scene preset. |
+| POST | `/api/v1/scene-presets/{preset_id}/recapture` | Re-capture current state into the preset. |
+| POST | `/api/v1/scene-presets/{preset_id}/activate` | Activate the preset (restore captured state). |
+
+## Sync clocks
+
+Shared clocks that drive linked animations with configurable speed.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/sync-clocks` | List all synchronization clocks. |
+| POST | `/api/v1/sync-clocks` | Create a sync clock. |
+| GET | `/api/v1/sync-clocks/{clock_id}` | Get a sync clock by ID. |
+| PUT | `/api/v1/sync-clocks/{clock_id}` | Update a clock (speed changes hot-applied). |
+| DELETE | `/api/v1/sync-clocks/{clock_id}` | Delete a clock (`409` if referenced). |
+| POST | `/api/v1/sync-clocks/{clock_id}/pause` | Pause the clock (freeze linked animations). |
+| POST | `/api/v1/sync-clocks/{clock_id}/resume` | Resume a paused clock. |
+| POST | `/api/v1/sync-clocks/{clock_id}/reset` | Reset the clock to `t=0`. |
+
+## Webhooks
+
+Inbound trigger endpoint for external services.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| POST | `/api/v1/webhooks/{token}` | Trigger an automation by secret token (`activate`/`deactivate`; rate-limited 30/min/IP). |
+
+## HTTP endpoints
+
+Outbound HTTP polling endpoints for integrations. 🔒 These require a real API key even on loopback.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/http/endpoints` | List all HTTP polling endpoints. |
+| POST | `/api/v1/http/endpoints` | Create an endpoint (URL, method, auth token, headers). |
+| GET | `/api/v1/http/endpoints/{endpoint_id}` | Get an endpoint by ID. |
+| PUT | `/api/v1/http/endpoints/{endpoint_id}` | Update an endpoint. |
+| DELETE | `/api/v1/http/endpoints/{endpoint_id}` | Delete an endpoint. |
+| POST | `/api/v1/http/endpoints/test` | One-shot test fetch to validate a config before saving. |
+| POST | `/api/v1/http/endpoints/{endpoint_id}/test` | Test a stored endpoint without re-entering its token. |
+
+## Game integration
+
+Game event ingestion, adapter metadata, presets, and diagnostics.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/game-integrations/presets` | List built-in effect presets. |
+| GET | `/api/v1/game-integrations` | List all game integration configs. |
+| POST | `/api/v1/game-integrations` | Create a game integration config. |
+| GET | `/api/v1/game-integrations/{integration_id}` | Get a config by ID. |
+| PUT | `/api/v1/game-integrations/{integration_id}` | Update a config. |
+| DELETE | `/api/v1/game-integrations/{integration_id}` | Delete a config. |
+| POST | `/api/v1/game-integrations/{integration_id}/event` | Ingest a game event (adapter-level auth; 16–64 Hz). |
+| GET | `/api/v1/game-integrations/{integration_id}/status` | Runtime status (connected state, event counts). |
+| GET | `/api/v1/game-integrations/{integration_id}/events` | Recent events for debugging (`limit`). |
+| GET | `/api/v1/game-adapters` | List adapter types and supported events. |
+| POST | `/api/v1/game-integrations/{integration_id}/apply-preset` | Apply a built-in preset (optionally replacing mappings). |
+| POST | `/api/v1/game-integrations/{integration_id}/auto-setup` | Write game config files and generate an auth token. |
+
+## Home Assistant
+
+Home Assistant WebSocket sources, entity discovery, and live status.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/home-assistant/sources` | List HA sources with status and entity counts (`?include_secrets=true` 🔒). |
+| POST | `/api/v1/home-assistant/sources` | Create an HA source (host, long-lived token, filters). |
+| GET | `/api/v1/home-assistant/sources/{source_id}` | Get an HA source (`?include_secrets=true` 🔒). |
+| PUT | `/api/v1/home-assistant/sources/{source_id}` | Update an HA source; refreshes the connection. |
+| DELETE | `/api/v1/home-assistant/sources/{source_id}` | Delete an HA source and release its runtime. |
+| GET | `/api/v1/home-assistant/sources/{source_id}/entities` | List available HA entities (live + cache fallback). |
+| POST | `/api/v1/home-assistant/sources/{source_id}/test` | Test connection/auth and report HA version. |
+| GET | `/api/v1/home-assistant/status` | Overall HA integration status per source. |
+
+## MQTT sources
+
+MQTT broker connections (sources) and status monitoring.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/mqtt/sources` | List MQTT sources with connection status. |
+| POST | `/api/v1/mqtt/sources` | Create an MQTT source (broker connection). |
+| GET | `/api/v1/mqtt/sources/{source_id}` | Get an MQTT source by ID. |
+| PUT | `/api/v1/mqtt/sources/{source_id}` | Update a source; restarts the broker runtime. |
+| DELETE | `/api/v1/mqtt/sources/{source_id}` | Delete a source and release its runtime. |
+| POST | `/api/v1/mqtt/sources/{source_id}/test` | Test connection to the broker (10s timeout). |
+| GET | `/api/v1/mqtt/status` | Overall MQTT integration status per source. |
+
+## Assets
+
+Media files (sounds, images, videos) used by effects and notifications.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/assets` | List assets (optional `asset_type` filter). |
+| GET | `/api/v1/assets/{asset_id}` | Get asset metadata by ID. |
+| POST | `/api/v1/assets` | Upload a new asset file (`multipart/form-data`). |
+| PUT | `/api/v1/assets/{asset_id}` | Update asset metadata. |
+| DELETE | `/api/v1/assets/{asset_id}` | Delete an asset (prebuilt assets are soft-deleted/restorable). |
+| GET | `/api/v1/assets/{asset_id}/file` | Serve the asset file (download). |
+| POST | `/api/v1/assets/restore-prebuilt` | Re-import any deleted prebuilt assets. |
+
+## Graph wiring
+
+The wiring-graph: schema registry, topology, dependents, validation, and subgraph duplication.
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/graph/schema` | Registry of connectable reference fields. |
+| GET | `/api/v1/graph` | Full wiring topology (nodes + edges) and validation report. |
+| GET | `/api/v1/graph/dependents/{kind}/{entity_id}` | Every entity that references `(kind, entity_id)`. |
+| POST | `/api/v1/graph/validate-connection` | Validate a proposed wiring edit (existence, kind, no cycle). |
+| POST | `/api/v1/graph/duplicate` | Deep-clone selected value/color-strip sources with remapped wiring. |
+
+## Web UI & PWA
+
+App-level routes served by FastAPI (not under `/api/v1`).
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/` | The web dashboard UI. |
+| GET | `/manifest.json` | PWA manifest (root scope). |
+| GET | `/sw.js` | Service worker (root scope). |
+| GET | `/openapi.json` | OpenAPI schema. |
+| GET | `/docs` | Swagger UI (interactive API docs). |
+| GET | `/redoc` | ReDoc API reference. |
 
 ---
 
-## Calibration
+## Next steps
 
-### GET /api/v1/devices/{device_id}/calibration
+- [Installation Guide](../INSTALLATION.md)
-
+- [Calibration Guide](CALIBRATION.md)
-Get calibration configuration.
+- Interactive, always-current schemas: [`/docs`](http://localhost:8080/docs)
-
-**Response:**
-```json
-{
-  "layout": "clockwise",
-  "start_position": "bottom_left",
-  "segments": [
-    {
-      "edge": "bottom",
-      "led_start": 0,
-      "led_count": 40,
-      "reverse": false
-    },
-    {
-      "edge": "right",
-      "led_start": 40,
-      "led_count": 30,
-      "reverse": false
-    },
-    {
-      "edge": "top",
-      "led_start": 70,
-      "led_count": 40,
-      "reverse": true
-    },
-    {
-      "edge": "left",
-      "led_start": 110,
-      "led_count": 40,
-      "reverse": true
-    }
-  ]
-}
-```
-
-### PUT /api/v1/devices/{device_id}/calibration
-
-Update calibration.
-
-**Request:** Same as GET response
-
-### POST /api/v1/devices/{device_id}/calibration/test
-
-Test calibration by lighting up specific edge.
-
-**Query Parameters:**
-- `edge`: Edge to test (top, right, bottom, left)
-- `color`: RGB color array (e.g., [255, 0, 0])
-
----
-
-## Metrics
-
-### GET /api/v1/devices/{device_id}/metrics
-
-Get detailed processing metrics.
-
-**Response:**
-```json
-{
-  "device_id": "device_abc123",
-  "processing": true,
-  "fps_actual": 29.8,
-  "fps_target": 30,
-  "uptime_seconds": 3600.5,
-  "frames_processed": 107415,
-  "errors_count": 2,
-  "last_error": null,
-  "last_update": "2026-02-06T12:00:00Z"
-}
-```
-
----
-
-## Error Responses
-
-All endpoints may return error responses in this format:
-
-```json
-{
-  "error": "ErrorType",
-  "message": "Human-readable error message",
-  "detail": {...},
-  "timestamp": "2026-02-06T12:00:00Z"
-}
-```
-
-**Common HTTP Status Codes:**
-- `200 OK` - Success
-- `201 Created` - Resource created
-- `204 No Content` - Success with no response body
-- `400 Bad Request` - Invalid request
-- `404 Not Found` - Resource not found
-- `500 Internal Server Error` - Server error
-
----
-
-## Interactive Documentation
-
-The server provides interactive API documentation:
-
-- **Swagger UI:** http://localhost:8080/docs
-- **ReDoc:** http://localhost:8080/redoc
-- **OpenAPI JSON:** http://localhost:8080/openapi.json

server/CLAUDE.md

@@ -6,33 +6,35 @@
 - `src/ledgrab/api/routes/` — REST API endpoints (one file per entity)
 - `src/ledgrab/api/schemas/` — Pydantic request/response models (one file per entity)
 - `src/ledgrab/core/` — Core business logic (capture, devices, audio, processing, automations)
-- `src/ledgrab/storage/` — Data models (dataclasses) and JSON persistence stores
+- `src/ledgrab/storage/` — Data models (dataclasses) and SQLite-backed persistence stores (`BaseSqliteStore`)
 - `src/ledgrab/utils/` — Utility functions (logging, monitor detection, SSRF validation, sound playback)
 - `src/ledgrab/static/` — Frontend files (TypeScript, CSS, locales)
 - `src/ledgrab/templates/` — Jinja2 HTML templates
 - `config/` — Configuration files (YAML)
-- `data/` — Runtime data (JSON stores, persisted state)
+- `data/` — Runtime data: SQLite database (`ledgrab.db`) + assets. Relocate the root with `LEDGRAB_DATA_DIR`.
 
 ## Entity & Storage Pattern
 
-Each entity follows: dataclass model (`storage/`) + JSON store (`storage/*_store.py`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`).
+Each entity follows: dataclass model (`storage/`) + SQLite store (`storage/*_store.py`, subclassing `BaseSqliteStore`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`).
+
+Stores keep an in-memory write-through cache over a per-entity SQLite table (the legacy `BaseJsonStore` still exists for reference but new stores use `BaseSqliteStore`). Schema/data shape changes go through `storage/data_migrations.py` — migrations are idempotent and tracked in a dedicated `data_migrations` audit table, so they run safely on every startup. **When renaming or restructuring stored fields, add a migration there** (see the Data Migration Policy in the root `CLAUDE.md`).
 
 ## Authentication
 
-Server uses API key authentication via Bearer token in `Authorization` header.
+API key authentication via Bearer token in the `Authorization` header (`Authorization: Bearer <key>`). WebSocket connections authenticate with a first-message handshake (`{"type":"auth","token":"<key>"}`). See `src/ledgrab/api/auth.py` for the canonical logic.
 
-- Config: `config/default_config.yaml` under `auth.api_keys`
+- Config: `config/default_config.yaml` under `auth.api_keys`; env var `LEDGRAB_AUTH__API_KEYS`
-- Env var: `LEDGRAB_AUTH__API_KEYS`
+- When `api_keys` is **empty** (default): **loopback** requests (`127.0.0.1` / `::1` / `localhost`) are allowed anonymously, but **LAN / remote** requests are rejected with `401`. Auth is *not* fully open.
-- When `api_keys` is empty (default), auth is disabled — all endpoints are open
+- When `api_keys` is **set**: a valid Bearer token is required from every client (loopback included).
-- To enable auth, add key entries (e.g. `dev: "your-secret-key"`)
+- `require_authenticated()` rejects even loopback-anonymous callers on sensitive endpoints (e.g. backup download, secret reveal).
 
 ## Common Tasks
 
 ### Adding a new API endpoint
 
-1. Create route file in `api/routes/`
+1. Create route file in `api/routes/` (define an `APIRouter(prefix="/api/v1/...")`)
 2. Define request/response schemas in `api/schemas/`
-3. Register the router in `main.py`
+3. Register the router in `api/__init__.py` (it aggregates every route module into the single `router` that `main.py` mounts)
 4. Restart the server
 5. Test via `/docs` (Swagger UI)
 

server/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ledgrab"
-version = "0.7.0"
+version = "0.8.1"
 description = "Ambient lighting system that captures screen content and drives LED strips in real time"
 authors = [
     {name = "Alexei Dolgolyov", email = "dolgolyov.alexei@gmail.com"}

server/src/ledgrab/__init__.py

@@ -9,7 +9,7 @@ from pathlib import Path
 # In dev (running from source without `pip install -e .`) and on Android
 # (Chaquopy embeds the source directly with no dist-info), we additionally
 # read pyproject.toml so the version is always correct without manual sync.
-_FALLBACK_VERSION = "0.7.0"
+_FALLBACK_VERSION = "0.8.1"
 
 
 def _read_pyproject_version() -> str | None:

server/src/ledgrab/__main__.py

@@ -39,8 +39,9 @@ _fix_embedded_tcl_paths()
 
 import uvicorn  # noqa: E402
 
-from ledgrab.config import get_config  # noqa: E402
+from ledgrab.config import Config, get_config  # noqa: E402
 from ledgrab.server_ref import set_server, set_tray  # noqa: E402
+from ledgrab.shutdown_state import GRACEFUL_SHUTDOWN_TIMEOUT  # noqa: E402
 from ledgrab.tray import PYSTRAY_AVAILABLE, TrayManager  # noqa: E402
 from ledgrab.utils import setup_logging, get_logger  # noqa: E402
 from ledgrab.utils.platform import is_windows  # noqa: E402
@@ -49,7 +50,8 @@ from ledgrab.utils.win_shutdown import WindowsShutdownGuard  # noqa: E402
 setup_logging()
 logger = get_logger(__name__)
 
-_ICON_PATH = Path(__file__).parent / "static" / "icons" / "icon-192.png"
+_ICON_PATH = Path(__file__).parent / "static" / "icons" / "icon-tray.png"
+_ICON_FALLBACK_PATH = Path(__file__).parent / "static" / "icons" / "icon-192.png"
 
 
 def _run_server(server: uvicorn.Server) -> None:
@@ -107,17 +109,28 @@ def _check_port(host: str, port: int) -> None:
             sys.exit(1)
 
 
-def main() -> None:
+def _build_server(config: Config) -> uvicorn.Server:
-    config = get_config()
+    """Construct the uvicorn Server with a bounded graceful-shutdown timeout.
-    _check_port(config.server.host, config.server.port)
 
+    Extracted so the graceful-shutdown bound is unit-testable — leaving it
+    unset (the uvicorn default of ``None``) is the regression that strands
+    LED targets and prevents the process from exiting.
+    """
     uv_config = uvicorn.Config(
         "ledgrab.main:app",
         host=config.server.host,
         port=config.server.port,
         log_level=config.server.log_level.lower(),
+        timeout_graceful_shutdown=GRACEFUL_SHUTDOWN_TIMEOUT,
     )
-    server = uvicorn.Server(uv_config)
+    return uvicorn.Server(uv_config)
+
+
+def main() -> None:
+    config = get_config()
+    _check_port(config.server.host, config.server.port)
+
+    server = _build_server(config)
     set_server(server)
 
     # Wire the OS-shutdown safety net. The lifespan in ``ledgrab.main`` signals
@@ -154,8 +167,9 @@ def main() -> None:
             ).start()
 
         # Tray on main thread (blocking)
+        tray_icon = _ICON_PATH if _ICON_PATH.exists() else _ICON_FALLBACK_PATH
         tray = TrayManager(
-            icon_path=_ICON_PATH,
+            icon_path=tray_icon,
             port=config.server.port,
             on_exit=lambda: _request_shutdown(server),
         )
@@ -163,9 +177,11 @@ def main() -> None:
         tray.run()
 
         # Tray exited — wait for server to finish its graceful shutdown.
-        # Use a longer join than the lifespan's own ~18 s budget so we don't
+        # Budget: the graceful-shutdown wait (GRACEFUL_SHUTDOWN_TIMEOUT) runs
-        # cut the DB checkpoint short on a slow disk.
+        # first, then the lifespan's own ~16 s shutdown (target restore + DB
-        server_thread.join(timeout=20)
+        # checkpoint). Join longer than their sum so a slow disk doesn't get
+        # the DB checkpoint cut short.
+        server_thread.join(timeout=25)
         if guard is not None:
             guard.stop()
     else:

server/src/ledgrab/android_entry.py

@@ -84,6 +84,8 @@ def start_server(data_dir: str, port: int = 8080, api_key: str | None = None) ->
             "LEDGRAB_AUTH__API_KEYS."
         )
 
+    from ledgrab.shutdown_state import GRACEFUL_SHUTDOWN_TIMEOUT
+
     uv_config = uvicorn.Config(
         "ledgrab.main:app",
         host=config.server.host,
@@ -91,6 +93,9 @@ def start_server(data_dir: str, port: int = 8080, api_key: str | None = None) ->
         log_level=config.server.log_level.lower(),
         # No uvloop/httptools on Android — use pure-Python asyncio
         loop="asyncio",
+        # Bound the graceful-shutdown wait so stop_server() can't hang forever
+        # on a lingering WebView events WebSocket — see shutdown_state for why.
+        timeout_graceful_shutdown=GRACEFUL_SHUTDOWN_TIMEOUT,
     )
 
     global _server, _loop

server/src/ledgrab/api/__init__.py

@@ -33,6 +33,8 @@ from .routes.audio_processing_templates import router as audio_processing_templa
 from .routes.audio_filters import router as audio_filters_router
 from .routes.pattern_templates import router as pattern_templates_router
 from .routes.preferences import router as preferences_router
+from .routes.snapshot import router as snapshot_router
+from .routes.graph import router as graph_router
 
 router = APIRouter()
 router.include_router(system_router)
@@ -66,5 +68,7 @@ router.include_router(audio_processing_templates_router)
 router.include_router(audio_filters_router)
 router.include_router(pattern_templates_router)
 router.include_router(preferences_router)
+router.include_router(snapshot_router)
+router.include_router(graph_router)
 
 __all__ = ["router"]

server/src/ledgrab/api/auth.py

@@ -80,6 +80,7 @@ def verify_api_key(
     if not config.auth.api_keys:
         # No keys configured — allow loopback only.
         if _is_loopback(client_host):
+            request.state.auth_label = "anonymous"
             return "anonymous"
         # Allow caller to authenticate explicitly even without configured keys?
         # No — there are no keys to compare against. Reject.
@@ -123,6 +124,9 @@ def verify_api_key(
     # Log successful authentication
     logger.debug(f"Authenticated as: {authenticated_as}")
 
+    # Stash the friendly label so the access-log middleware can attribute the
+    # request to a client without re-running the token comparison.
+    request.state.auth_label = authenticated_as
     return authenticated_as
 
 

server/src/ledgrab/api/graph_schema.py

@@ -0,0 +1,609 @@
+"""Authoritative wiring-graph schema and topology engine.
+
+This module is the single source of truth for **which reference fields connect
+which entity kinds**. The frontend graph editor historically hard-coded the same
+information in two places (``graph-connections.ts`` ``CONNECTION_MAP`` and
+``graph-layout.ts`` ``buildGraph``); the ``GET /api/v1/graph/schema`` endpoint
+now serves this registry so the client can render ports and edges generically
+and the two never drift.
+
+This registry is a *superset* of the current frontend ``buildGraph``: it also
+declares real references that ``buildGraph`` does not yet draw (e.g.
+``value_source.value_source_id`` chaining and ``value_source.color_strip_source_id``).
+The backend is authoritative; the client is expected to converge on it.
+
+Everything in this module is pure (operates on plain dicts), so the topology
+build, dependency lookup, cycle and dangling-reference detection are all unit
+testable without booting the app or any store.
+
+Field-path grammar (the ``field`` of a :class:`ConnectionField`):
+
+* ``"device_id"``                  — a top-level string id.
+* ``"brightness.source_id"``       — a nested object; ``brightness`` may be a
+  plain number (unbound :class:`BindableFloat`) or ``{"value", "source_id"}``.
+* ``"settings.pattern_template_id"`` — arbitrarily deep object access.
+* ``"layers[].source_id"``         — ``layers`` is a list; read ``source_id``
+  from every element.
+* ``"calibration.lines[].picture_source_id"`` — object → list → field.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass, is_dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ConnectionField:
+    """One connectable reference: ``target_kind.field`` points at ``source_kind``."""
+
+    target_kind: str
+    """Entity kind that *holds* the reference (the consumer / referrer)."""
+    field: str
+    """Dot-path to the reference value (see module docstring grammar)."""
+    source_kind: str
+    """Entity kind being referenced (the producer / source)."""
+    edge_type: str
+    """Edge category, used by the client for colour and port grouping."""
+    bindable: bool = False
+    """True when the slot is a :class:`BindableFloat`/``BindableColor`` value binding."""
+    nested: bool = False
+    """True when the field lives inside a nested object/list (dotted path)."""
+
+    @property
+    def is_list(self) -> bool:
+        """True when any path segment iterates a list (``foo[]``)."""
+        return "[]" in self.field
+
+
+# ── Entity kinds & their human "type" attribute ────────────────────────────
+# Mirrors the frontend buildGraph(): kind → the serialized field that carries
+# the entity's subtype (used only for the node label / icon).
+NODE_TYPE_FIELD: dict[str, str] = {
+    "device": "device_type",
+    "capture_template": "engine_type",
+    "pp_template": "",
+    "audio_template": "engine_type",
+    "pattern_template": "",
+    "picture_source": "stream_type",
+    "audio_source": "source_type",
+    "value_source": "source_type",
+    "color_strip_source": "source_type",
+    "sync_clock": "",
+    "output_target": "target_type",
+    "scene_preset": "",
+    "automation": "",
+    "cspt": "",
+}
+
+ENTITY_KINDS: tuple[str, ...] = tuple(NODE_TYPE_FIELD.keys())
+
+
+# ── The registry ───────────────────────────────────────────────────────────
+# NOTE: ``gradient`` and ``ha_source`` reference fields are intentionally
+# omitted — they are not first-class graph node kinds, so wiring them would
+# only ever produce dangling-reference noise.
+CONNECTION_SCHEMA: tuple[ConnectionField, ...] = (
+    # ── Picture sources ──
+    ConnectionField("picture_source", "capture_template_id", "capture_template", "template"),
+    ConnectionField("picture_source", "source_stream_id", "picture_source", "picture"),
+    ConnectionField("picture_source", "postprocessing_template_id", "pp_template", "template"),
+    # ── Audio sources ──
+    ConnectionField("audio_source", "audio_template_id", "audio_template", "audio"),
+    ConnectionField("audio_source", "audio_source_id", "audio_source", "audio"),
+    # ── Value sources ──
+    ConnectionField("value_source", "audio_source_id", "audio_source", "audio"),
+    ConnectionField("value_source", "picture_source_id", "picture_source", "picture"),
+    ConnectionField("value_source", "value_source_id", "value_source", "value"),
+    ConnectionField("value_source", "color_strip_source_id", "color_strip_source", "colorstrip"),
+    # AnimatedColorValueSource references a sync clock for shared timing.
+    ConnectionField("value_source", "clock_id", "sync_clock", "clock"),
+    # ── Color strip sources (top-level) ──
+    ConnectionField("color_strip_source", "picture_source_id", "picture_source", "picture"),
+    ConnectionField("color_strip_source", "audio_source_id", "audio_source", "audio"),
+    ConnectionField("color_strip_source", "clock_id", "sync_clock", "clock"),
+    ConnectionField("color_strip_source", "input_source_id", "color_strip_source", "colorstrip"),
+    ConnectionField("color_strip_source", "processing_template_id", "cspt", "template"),
+    # ── Color strip sources (BindableFloat value bindings) ──
+    *(
+        ConnectionField(
+            "color_strip_source",
+            f"{prop}.source_id",
+            "value_source",
+            "value",
+            bindable=True,
+            nested=True,
+        )
+        for prop in (
+            "smoothing",
+            "sensitivity",
+            "intensity",
+            "scale",
+            "speed",
+            "wind_strength",
+            "temperature_influence",
+            "sound_volume",
+            "timeout",
+            "brightness",
+        )
+    ),
+    # ── Color strip sources (BindableColor value bindings) ──
+    # NOTE: `bindable` here is *structural* (these are BindableColor fields). They
+    # are NOT usefully wireable from the graph: a ValueStream yields a scalar
+    # (`get_value() -> float`) and every colour consumer reads the static RGB via
+    # `bcolor()` (source_id ignored at runtime). The graph editor keeps them
+    # read-only; do not enable them without a colour-producing value source.
+    *(
+        ConnectionField(
+            "color_strip_source",
+            f"{prop}.source_id",
+            "value_source",
+            "value",
+            bindable=True,
+            nested=True,
+        )
+        for prop in ("color", "color_peak", "fallback_color", "default_color")
+    ),
+    # ── Color strip sources (composite layers / mapped zones / calibration) ──
+    ConnectionField(
+        "color_strip_source", "layers[].source_id", "color_strip_source", "colorstrip", nested=True
+    ),
+    ConnectionField(
+        "color_strip_source",
+        "layers[].brightness_source_id",
+        "value_source",
+        "value",
+        bindable=True,
+        nested=True,
+    ),
+    ConnectionField(
+        "color_strip_source", "layers[].processing_template_id", "cspt", "template", nested=True
+    ),
+    ConnectionField(
+        "color_strip_source", "zones[].source_id", "color_strip_source", "colorstrip", nested=True
+    ),
+    ConnectionField(
+        "color_strip_source",
+        "calibration.lines[].picture_source_id",
+        "picture_source",
+        "picture",
+        nested=True,
+    ),
+    # ── Output targets ──
+    ConnectionField("output_target", "device_id", "device", "device"),
+    ConnectionField("output_target", "color_strip_source_id", "color_strip_source", "colorstrip"),
+    ConnectionField(
+        "output_target", "brightness.source_id", "value_source", "value", bindable=True, nested=True
+    ),
+    ConnectionField(
+        "output_target", "transition.source_id", "value_source", "value", bindable=True, nested=True
+    ),
+    ConnectionField(
+        "output_target", "settings.pattern_template_id", "pattern_template", "template", nested=True
+    ),
+    ConnectionField(
+        "output_target",
+        "settings.brightness.source_id",
+        "value_source",
+        "value",
+        bindable=True,
+        nested=True,
+    ),
+    # ── Scene presets ──
+    ConnectionField("scene_preset", "targets[].target_id", "output_target", "scene", nested=True),
+    # ── Automations ──
+    ConnectionField("automation", "scene_preset_id", "scene_preset", "scene"),
+    ConnectionField("automation", "deactivation_scene_preset_id", "scene_preset", "scene"),
+    # ── Devices ──
+    ConnectionField("device", "default_css_processing_template_id", "cspt", "template"),
+)
+
+
+def schema_for_kind(kind: str) -> list[ConnectionField]:
+    """Every connectable field whose *referrer* is ``kind``."""
+    return [c for c in CONNECTION_SCHEMA if c.target_kind == kind]
+
+
+# BindableColor slots are structurally bindable but NOT graph-editable: a
+# ValueStream yields a scalar (``get_value() -> float``) and colour consumers
+# read the static RGB via ``bcolor()`` (source_id ignored at runtime), so a
+# value source cannot drive a colour.
+_COLOR_BINDABLE_FIELDS: frozenset[str] = frozenset(
+    {
+        "color.source_id",
+        "color_peak.source_id",
+        "fallback_color.source_id",
+        "default_color.source_id",
+    }
+)
+
+
+def is_editable(cf: ConnectionField) -> bool:
+    """Whether a field can be wired from the graph.
+
+    Editable = a top-level reference, or a single-level ``BindableFloat`` slot.
+    List slots (need an element index), double-nested fields, and the dead
+    colour bindings stay read-only.
+    """
+    if cf.is_list:
+        return False
+    if not cf.nested:
+        return True
+    return cf.bindable and cf.field.count(".") == 1 and cf.field not in _COLOR_BINDABLE_FIELDS
+
+
+def schema_as_dicts() -> list[dict[str, Any]]:
+    """Serialize the registry for the ``/graph/schema`` endpoint."""
+    return [
+        {
+            "target_kind": c.target_kind,
+            "field": c.field,
+            "source_kind": c.source_kind,
+            "edge_type": c.edge_type,
+            "bindable": c.bindable,
+            "nested": c.nested,
+            "is_list": c.is_list,
+            "editable": is_editable(c),
+        }
+        for c in CONNECTION_SCHEMA
+    ]
+
+
+# ── Reference extraction ────────────────────────────────────────────────────
+
+
+def extract_refs(entity: dict[str, Any], field_path: str) -> list[str]:
+    """Resolve a (possibly nested/list) ``field_path`` to its referenced ids.
+
+    Returns only non-empty string ids. Tolerant of missing keys, ``None``
+    values and unbound bindables (a plain number where an object was expected).
+    """
+    current: list[Any] = [entity]
+    for segment in field_path.split("."):
+        is_list = segment.endswith("[]")
+        key = segment[:-2] if is_list else segment
+        nxt: list[Any] = []
+        for obj in current:
+            if not isinstance(obj, dict):
+                continue
+            val = obj.get(key)
+            if is_list:
+                if isinstance(val, list):
+                    nxt.extend(val)
+            elif val is not None:
+                nxt.append(val)
+        current = nxt
+    return [v for v in current if isinstance(v, str) and v]
+
+
+def remap_refs(entity: dict[str, Any], field_path: str, id_map: dict[str, str]) -> int:
+    """Rewrite referenced ids under ``field_path`` *in place*, using ``id_map``.
+
+    The write-twin of :func:`extract_refs`: it walks the same dot/list/bindable
+    grammar and replaces any leaf id present in ``id_map`` with its mapped value.
+    Ids absent from ``id_map`` (references to entities outside the remap set) are
+    left untouched, so a clone keeps sharing its un-cloned dependencies. Unbound
+    bindables (a plain number where an object was expected) and missing keys are
+    tolerated. Returns the number of ids rewritten.
+    """
+    segments = field_path.split(".")
+    # Descend to the container(s) that hold the final key.
+    parents: list[Any] = [entity]
+    for segment in segments[:-1]:
+        is_list = segment.endswith("[]")
+        key = segment[:-2] if is_list else segment
+        nxt: list[Any] = []
+        for obj in parents:
+            if not isinstance(obj, dict):
+                continue
+            val = obj.get(key)
+            if is_list:
+                if isinstance(val, list):
+                    nxt.extend(val)
+            elif isinstance(val, dict):
+                nxt.append(val)
+        parents = nxt
+
+    last = segments[-1]
+    last_is_list = last.endswith("[]")
+    key = last[:-2] if last_is_list else last
+    count = 0
+    for obj in parents:
+        if not isinstance(obj, dict):
+            continue
+        val = obj.get(key)
+        if last_is_list:
+            if isinstance(val, list):
+                for i, item in enumerate(val):
+                    if isinstance(item, str) and item in id_map:
+                        val[i] = id_map[item]
+                        count += 1
+        elif isinstance(val, str) and val in id_map:
+            obj[key] = id_map[val]
+            count += 1
+    return count
+
+
+def serialize_entity(model: Any) -> dict[str, Any]:
+    """Best-effort serialize a storage model to a plain dict for graph use.
+
+    Prefers ``dataclasses.asdict`` (pure structural, recurses bindables/lists,
+    invokes no managers), falling back to ``to_dict()`` then ``{}``.
+    """
+    if is_dataclass(model) and not isinstance(model, type):
+        try:
+            return asdict(model)
+        except Exception as exc:  # noqa: BLE001 — defensive: never let one model break the graph
+            logger.debug("graph: asdict failed for %r: %s", type(model).__name__, exc)
+    to_dict = getattr(model, "to_dict", None)
+    if callable(to_dict):
+        try:
+            result = to_dict()
+            if isinstance(result, dict):
+                return result
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("graph: to_dict failed for %r: %s", type(model).__name__, exc)
+    logger.warning(
+        "graph: could not serialize model %r; excluding from graph", type(model).__name__
+    )
+    return {}
+
+
+def graph_field_roots(kind: str) -> set[str]:
+    """Top-level keys the graph needs for ``kind``: ``id``/``name``, the subtype
+    field, and the root segment of every reference path for that kind."""
+    roots: set[str] = {"id", "name"}
+    type_field = NODE_TYPE_FIELD.get(kind, "")
+    if type_field:
+        roots.add(type_field)
+    for cf in CONNECTION_SCHEMA:
+        if cf.target_kind == kind:
+            roots.add(cf.field.split(".", 1)[0].removesuffix("[]"))
+    return roots
+
+
+def serialize_entity_for_graph(kind: str, model: Any) -> dict[str, Any]:
+    """Serialize a model and project it to ONLY the keys the graph needs.
+
+    This projection is a **security boundary**: a full ``asdict``/``to_dict``
+    can carry secrets (webhook tokens, device/HA/MQTT credentials), so every
+    field except ``id``/``name``, the subtype field and reference-path roots is
+    dropped before the data reaches the graph API.
+    """
+    full = serialize_entity(model)
+    roots = graph_field_roots(kind)
+    return {k: v for k, v in full.items() if k in roots}
+
+
+# ── Topology / validation ───────────────────────────────────────────────────
+
+
+def _node_from(kind: str, entity: dict[str, Any]) -> dict[str, Any] | None:
+    eid = entity.get("id")
+    if not isinstance(eid, str) or not eid:
+        return None
+    type_field = NODE_TYPE_FIELD.get(kind, "")
+    subtype = entity.get(type_field, "") if type_field else ""
+    return {
+        "id": eid,
+        "kind": kind,
+        "name": entity.get("name") or eid,
+        "type": subtype if isinstance(subtype, str) else "",
+    }
+
+
+def build_topology(entities_by_kind: dict[str, list[dict[str, Any]]]) -> dict[str, Any]:
+    """Build the full wiring graph + a validation report.
+
+    Args:
+        entities_by_kind: ``{kind: [serialized_entity_dict, ...]}``.
+
+    Returns a dict with ``nodes``, ``edges`` and ``issues`` (``orphans``,
+    ``broken_refs``, ``cycles``).
+    """
+    nodes: list[dict[str, Any]] = []
+    node_ids: set[str] = set()
+    for kind in ENTITY_KINDS:
+        for entity in entities_by_kind.get(kind, []):
+            node = _node_from(kind, entity)
+            if node and node["id"] not in node_ids:
+                node_ids.add(node["id"])
+                nodes.append(node)
+
+    edges: list[dict[str, Any]] = []
+    broken_refs: list[dict[str, str]] = []
+    for cf in CONNECTION_SCHEMA:
+        for entity in entities_by_kind.get(cf.target_kind, []):
+            referrer = entity.get("id")
+            if not isinstance(referrer, str) or not referrer:
+                continue
+            for ref in extract_refs(entity, cf.field):
+                if ref not in node_ids:
+                    broken_refs.append({"ref": ref, "by": referrer, "field": cf.field})
+                    continue
+                edges.append(
+                    {
+                        "from": ref,
+                        "to": referrer,
+                        "field": cf.field,
+                        "edge_type": cf.edge_type,
+                        "nested": cf.nested,
+                    }
+                )
+
+    connected: set[str] = set()
+    for e in edges:
+        connected.add(e["from"])
+        connected.add(e["to"])
+    orphans = sorted(nid for nid in node_ids if nid not in connected)
+    cycles = sorted(detect_cycles(edges))
+
+    return {
+        "nodes": nodes,
+        "edges": edges,
+        "issues": {
+            "orphans": orphans,
+            "broken_refs": broken_refs,
+            "cycles": cycles,
+        },
+    }
+
+
+def find_dependents(
+    entities_by_kind: dict[str, list[dict[str, Any]]], kind: str, entity_id: str
+) -> list[dict[str, str]]:
+    """Return every entity that references ``(kind, entity_id)``.
+
+    ``kind`` is the kind of the *referenced* entity; matching schema entries are
+    those whose ``source_kind == kind``.
+    """
+    name_by_id: dict[str, str] = {}
+    for k in ENTITY_KINDS:
+        for entity in entities_by_kind.get(k, []):
+            eid = entity.get("id")
+            if isinstance(eid, str):
+                name_by_id[eid] = entity.get("name") or eid
+
+    dependents: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for cf in CONNECTION_SCHEMA:
+        if cf.source_kind != kind:
+            continue
+        for entity in entities_by_kind.get(cf.target_kind, []):
+            referrer = entity.get("id")
+            if not isinstance(referrer, str):
+                continue
+            if entity_id in extract_refs(entity, cf.field):
+                key = (referrer, cf.field)
+                if key in seen:
+                    continue
+                seen.add(key)
+                dependents.append(
+                    {
+                        "id": referrer,
+                        "kind": cf.target_kind,
+                        "name": name_by_id.get(referrer, referrer),
+                        "field": cf.field,
+                    }
+                )
+    return dependents
+
+
+def detect_cycles(edges: list[dict[str, Any]]) -> set[str]:
+    """Return every node id that participates in a directed cycle (from→to)."""
+    adj: dict[str, list[str]] = {}
+    for e in edges:
+        adj.setdefault(e["from"], []).append(e["to"])
+
+    WHITE, GRAY, BLACK = 0, 1, 2
+    color: dict[str, int] = {}
+    in_cycle: set[str] = set()
+
+    for start in list(adj.keys()):
+        if color.get(start, WHITE) != WHITE:
+            continue
+        stack: list[tuple[str, int]] = [(start, 0)]
+        path: list[str] = [start]
+        color[start] = GRAY
+        while stack:
+            node, idx = stack[-1]
+            neighbors = adj.get(node, [])
+            if idx < len(neighbors):
+                stack[-1] = (node, idx + 1)
+                nxt = neighbors[idx]
+                c = color.get(nxt, WHITE)
+                if c == GRAY:
+                    if nxt in path:
+                        i = path.index(nxt)
+                        in_cycle.update(path[i:])
+                elif c == WHITE:
+                    color[nxt] = GRAY
+                    path.append(nxt)
+                    stack.append((nxt, 0))
+            else:
+                color[node] = BLACK
+                if path and path[-1] == node:
+                    path.pop()
+                stack.pop()
+    return in_cycle
+
+
+def _reachable(edges: list[dict[str, Any]], start: str, goal: str) -> bool:
+    """True if ``goal`` is reachable from ``start`` following from→to edges."""
+    if start == goal:
+        return True
+    adj: dict[str, list[str]] = {}
+    for e in edges:
+        adj.setdefault(e["from"], []).append(e["to"])
+    seen = {start}
+    queue = [start]
+    while queue:
+        cur = queue.pop()
+        for nxt in adj.get(cur, []):
+            if nxt == goal:
+                return True
+            if nxt not in seen:
+                seen.add(nxt)
+                queue.append(nxt)
+    return False
+
+
+def would_create_cycle(edges: list[dict[str, Any]], source_id: str, target_id: str) -> bool:
+    """Would wiring ``source_id`` into ``target_id`` (edge source→target) loop?
+
+    A cycle forms if ``source_id`` is already reachable from ``target_id`` via
+    the existing data-flow edges (so the new edge would close the loop), or the
+    two are the same node.
+    """
+    if source_id == target_id:
+        return True
+    return _reachable(edges, target_id, source_id)
+
+
+def _entity_exists(
+    entities_by_kind: dict[str, list[dict[str, Any]]], kind: str, entity_id: str
+) -> bool:
+    return any(e.get("id") == entity_id for e in entities_by_kind.get(kind, []))
+
+
+def validate_connection(
+    entities_by_kind: dict[str, list[dict[str, Any]]],
+    target_kind: str,
+    target_id: str,
+    field: str,
+    source_id: str,
+) -> tuple[bool, str | None]:
+    """Validate a proposed wiring edit before it is persisted.
+
+    Checks, in order: the field is a known connectable reference; the target
+    exists; (when not detaching) the source exists and is of the registry's
+    expected kind; and the edit would not create a dependency cycle. Returns
+    ``(ok, error_message)``. Detaching (empty ``source_id``) is always allowed.
+    """
+    cf = next(
+        (c for c in CONNECTION_SCHEMA if c.target_kind == target_kind and c.field == field),
+        None,
+    )
+    if cf is None:
+        return False, f"Unknown connection field: {target_kind}.{field}"
+    if not is_editable(cf):
+        # List slots (need an element index), double-nested fields, and dead
+        # colour bindings can't be wired from the graph — edit via the entity
+        # editor instead.
+        return False, f"Field '{field}' is not editable via the graph"
+    if not _entity_exists(entities_by_kind, target_kind, target_id):
+        return False, f"Target entity not found: {target_id}"
+    if not source_id:
+        return True, None  # detaching a slot is always valid
+    if not _entity_exists(entities_by_kind, cf.source_kind, source_id):
+        return False, f"Source {cf.source_kind} not found: {source_id}"
+    # Cycle check: ignore the edge currently occupying this slot, since the
+    # write replaces it.
+    topo = build_topology(entities_by_kind)
+    edges = [e for e in topo["edges"] if not (e["to"] == target_id and e["field"] == field)]
+    if would_create_cycle(edges, source_id, target_id):
+        return False, "Connection would create a dependency cycle"
+    return True, None

server/src/ledgrab/api/routes/_mqtt_validation.py

@@ -0,0 +1,25 @@
+"""Shared MQTT-source validation for route handlers.
+
+Both the device routes and the output-target routes accept an
+``mqtt_source_id`` that must reference an existing ``MQTTSource``. This module
+is the single source of truth for that check so the two callers cannot drift.
+"""
+
+from fastapi import HTTPException
+
+from ledgrab.storage.base_store import EntityNotFoundError
+from ledgrab.storage.mqtt_source_store import MQTTSourceStore
+
+
+def validate_mqtt_source_exists(mqtt_store: MQTTSourceStore, mqtt_source_id: str | None) -> None:
+    """Ensure a referenced MQTT source exists.
+
+    Empty / ``None`` is allowed (unconfigured = "first available broker").
+    Raises ``HTTPException(422)`` if a non-empty id does not resolve.
+    """
+    if not mqtt_source_id:
+        return
+    try:
+        mqtt_store.get(mqtt_source_id)
+    except (ValueError, EntityNotFoundError):
+        raise HTTPException(status_code=422, detail=f"MQTT source {mqtt_source_id} not found")

server/src/ledgrab/api/routes/backup.py

@@ -11,6 +11,7 @@ import sys
 import threading
 import zipfile
 from pathlib import Path
+from typing import Any
 
 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
 from fastapi.responses import StreamingResponse
@@ -38,28 +39,59 @@ _SERVER_DIR = Path(__file__).resolve().parents[4]
 
 
 def _schedule_restart() -> None:
-    """Spawn a restart script after a short delay so the HTTP response completes."""
+    """Spawn a restart script after a short delay so the HTTP response completes.
 
-    def _restart():
+    stdout/stderr of the spawned script are redirected to ``<server>/restart.log``
+    so a silent failure (PowerShell not on PATH, restart.ps1 erroring, etc.)
+    leaves evidence on disk instead of vanishing into a detached child.
+    """
+
+    def _restart() -> None:
         import time
 
         time.sleep(1)
+
+        # Annotated as ``dict[str, Any]`` because the value union spans
+        # int flags (Windows ``creationflags``) and bool (POSIX
+        # ``start_new_session``); a narrower union confuses ``**`` unpacking.
+        popen_kwargs: dict[str, Any]
         if sys.platform == "win32":
-            subprocess.Popen(
+            script = _SERVER_DIR / "restart.ps1"
-                [
+            cmd = ["powershell", "-ExecutionPolicy", "Bypass", "-File", str(script)]
-                    "powershell",
+            popen_kwargs = {
-                    "-ExecutionPolicy",
+                "creationflags": (
-                    "Bypass",
+                    subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
-                    "-File",
+                ),
-                    str(_SERVER_DIR / "restart.ps1"),
+            }
-                ],
-                creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP,
-            )
         else:
-            subprocess.Popen(
+            script = _SERVER_DIR / "restart.sh"
-                ["bash", str(_SERVER_DIR / "restart.sh")],
+            cmd = ["bash", str(script)]
-                start_new_session=True,
+            popen_kwargs = {"start_new_session": True}
-            )
+
+        if not script.is_file():
+            logger.error("Restart script missing: %s", script)
+            return
+
+        log_path = _SERVER_DIR / "restart.log"
+        try:
+            # Open in append mode so multiple restarts accumulate; the child
+            # owns its own duped handle, so closing here in the parent is safe.
+            with open(log_path, "ab") as log_file:
+                log_file.write(
+                    f"\n--- restart spawned at {time.strftime('%Y-%m-%d %H:%M:%S')} ---\n".encode()
+                )
+                log_file.flush()
+                proc = subprocess.Popen(
+                    cmd,
+                    stdout=log_file,
+                    stderr=subprocess.STDOUT,
+                    **popen_kwargs,
+                )
+            logger.info("Restart script launched: %s (PID %s, log %s)", cmd[0], proc.pid, log_path)
+        except OSError as e:
+            logger.error("Failed to launch restart script %s: %s", script, e, exc_info=True)
+        except Exception as e:
+            logger.error("Unexpected error launching restart script: %s", e, exc_info=True)
 
     threading.Thread(target=_restart, daemon=True).start()
 

server/src/ledgrab/api/routes/devices.py

@@ -13,6 +13,7 @@ from ledgrab.core.devices.led_client import (
 from ledgrab.api.dependencies import (
     fire_entity_event,
     get_device_store,
+    get_mqtt_store,
     get_output_target_store,
     get_processor_manager,
 )
@@ -33,10 +34,13 @@ from ledgrab.api.schemas.devices import (
 )
 from ledgrab.core.processing.processor_manager import ProcessorManager
 from ledgrab.storage import DeviceStore
+from ledgrab.storage.mqtt_source_store import MQTTSourceStore
 from ledgrab.storage.output_target_store import OutputTargetStore
 from ledgrab.utils import get_logger
 from ledgrab.utils.url_scheme import infer_http_scheme
 
+from ._mqtt_validation import validate_mqtt_source_exists
+
 logger = get_logger(__name__)
 
 router = APIRouter()
@@ -105,6 +109,7 @@ def _device_to_response(device) -> DeviceResponse:
         gamesense_device_type=device.gamesense_device_type,
         ble_family=device.ble_family,
         ble_govee_key=device.ble_govee_key,
+        mqtt_source_id=getattr(device, "mqtt_source_id", "") or "",
         default_css_processing_template_id=device.default_css_processing_template_id,
         group_device_ids=device.group_device_ids,
         group_mode=device.group_mode,
@@ -124,11 +129,13 @@ async def create_device(
     _auth: AuthRequired,
     store: DeviceStore = Depends(get_device_store),
     manager: ProcessorManager = Depends(get_processor_manager),
+    mqtt_store: MQTTSourceStore = Depends(get_mqtt_store),
 ):
     """Create and attach a new LED device."""
     try:
         device_type = device_data.device_type
         logger.info(f"Creating {device_type} device: {device_data.name}")
+        validate_mqtt_source_exists(mqtt_store, device_data.mqtt_source_id)
 
         # ── Group device: validate children + compute LED count ──
         if device_type == "group":
@@ -287,6 +294,7 @@ async def create_device(
             gamesense_device_type=device_data.gamesense_device_type or "keyboard",
             ble_family=device_data.ble_family or "",
             ble_govee_key=device_data.ble_govee_key or "",
+            mqtt_source_id=device_data.mqtt_source_id or "",
             group_device_ids=group_device_ids,
             group_mode=group_mode,
         )
@@ -543,12 +551,14 @@ async def update_device(
     _auth: AuthRequired,
     store: DeviceStore = Depends(get_device_store),
     manager: ProcessorManager = Depends(get_processor_manager),
+    mqtt_store: MQTTSourceStore = Depends(get_mqtt_store),
 ):
     """Update device information."""
     try:
         # Group-specific validation before applying update
         existing = store.get_device(device_id)
         is_group = existing.device_type == "group"
+        validate_mqtt_source_exists(mqtt_store, update_data.mqtt_source_id)
 
         # Normalize URL the same way we do on create:
         #   * always rstrip trailing slashes (so PUT-with-trailing-/ matches
@@ -634,6 +644,7 @@ async def update_device(
             gamesense_device_type=update_data.gamesense_device_type,
             ble_family=update_data.ble_family,
             ble_govee_key=update_data.ble_govee_key,
+            mqtt_source_id=update_data.mqtt_source_id,
             group_device_ids=update_data.group_device_ids,
             group_mode=update_data.group_mode,
             icon=update_data.icon,
@@ -669,6 +680,10 @@ async def update_device(
         fire_entity_event("device", "updated", device_id)
         return _device_to_response(device)
 
+    except HTTPException:
+        # Intentional 4xx (e.g. unknown mqtt_source_id, group validation)
+        # must propagate unchanged — not be masked as a 500.
+        raise
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e))
     except Exception as e:
@@ -777,6 +792,32 @@ async def ping_device(
 # ===== WLED BRIGHTNESS ENDPOINTS =====
 
 
+async def resolve_device_brightness(device, manager: ProcessorManager) -> int | None:
+    """Resolve a device's current brightness for aggregate/batch reads.
+
+    Mirrors GET /brightness but degrades to ``None`` instead of raising, so one
+    unreachable device can't fail a whole snapshot. Reads the server-side cache
+    first and only touches hardware when the cache is cold, then populates it so
+    subsequent reads are I/O-free.
+    """
+    if "brightness_control" not in get_device_capabilities(device.device_type):
+        return None
+    ds = manager.find_device_state(device.id)
+    if ds and ds.hardware_brightness is not None:
+        return ds.hardware_brightness
+    try:
+        provider = get_provider(device.device_type)
+        bri = await provider.get_brightness(device.url)
+        if ds:
+            ds.hardware_brightness = bri
+        return bri
+    except NotImplementedError:
+        return device.software_brightness
+    except Exception as e:
+        logger.warning("Failed to resolve brightness for device %s: %s", device.id, e)
+        return None
+
+
 @router.get("/api/v1/devices/{device_id}/brightness", tags=["Settings"])
 async def get_device_brightness(
     device_id: str,

server/src/ledgrab/api/routes/graph.py

@@ -0,0 +1,249 @@
+"""Wiring-graph endpoints: schema registry, full topology, and dependents.
+
+These power the visual graph editor (and any other client) with a single
+authoritative view of how entities are wired together:
+
+* ``GET /api/v1/graph/schema``                  — the connectable-field registry.
+* ``GET /api/v1/graph``                          — nodes + edges + validation.
+* ``GET /api/v1/graph/dependents/{kind}/{id}``   — what references an entity.
+
+All heavy logic lives in :mod:`ledgrab.api.graph_schema` (pure, unit-tested);
+this layer only gathers serialized entities from the stores and delegates.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+from fastapi import APIRouter, HTTPException
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, Field
+
+from ledgrab.api import dependencies as deps
+from ledgrab.api.auth import AuthRequired
+from ledgrab.api.graph_schema import (
+    ENTITY_KINDS,
+    NODE_TYPE_FIELD,
+    build_topology,
+    extract_refs,
+    find_dependents,
+    remap_refs,
+    schema_as_dicts,
+    schema_for_kind,
+    serialize_entity,
+    serialize_entity_for_graph,
+    validate_connection,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionValidationRequest(BaseModel):
+    """A proposed wiring edit: set ``target_kind.field`` to ``source_id``."""
+
+    target_kind: str
+    target_id: str
+    field: str
+    source_id: str = Field(default="", description="Empty string detaches the slot.")
+
+
+router = APIRouter()
+
+# kind → dependency getter for the store that owns that entity kind.
+_KIND_STORES: dict[str, Callable[[], Any]] = {
+    "device": deps.get_device_store,
+    "capture_template": deps.get_template_store,
+    "pp_template": deps.get_pp_template_store,
+    "audio_template": deps.get_audio_template_store,
+    "pattern_template": deps.get_pattern_template_store,
+    "picture_source": deps.get_picture_source_store,
+    "audio_source": deps.get_audio_source_store,
+    "value_source": deps.get_value_source_store,
+    "color_strip_source": deps.get_color_strip_store,
+    "sync_clock": deps.get_sync_clock_store,
+    "output_target": deps.get_output_target_store,
+    "scene_preset": deps.get_scene_preset_store,
+    "automation": deps.get_automation_store,
+    "cspt": deps.get_cspt_store,
+}
+
+
+def _gather_entities() -> dict[str, list[dict[str, Any]]]:
+    """Serialize every entity, keyed by kind. Missing stores yield ``[]``."""
+    out: dict[str, list[dict[str, Any]]] = {}
+    for kind, getter in _KIND_STORES.items():
+        try:
+            store = getter()
+            models = store.get_all()
+        except (
+            Exception
+        ) as exc:  # noqa: BLE001 — an uninitialized/failing store must not 500 the graph
+            logger.warning("graph: store for kind %s unavailable: %s", kind, exc)
+            out[kind] = []
+            continue
+        out[kind] = [serialize_entity_for_graph(kind, m) for m in models]
+    return out
+
+
+@router.get("/api/v1/graph/schema", tags=["Graph"])
+async def get_graph_schema(_auth: AuthRequired) -> dict[str, Any]:
+    """Return the authoritative registry of connectable reference fields."""
+    return {
+        "kinds": list(ENTITY_KINDS),
+        "node_type_field": NODE_TYPE_FIELD,
+        "connections": schema_as_dicts(),
+    }
+
+
+@router.get("/api/v1/graph", tags=["Graph"])
+async def get_graph(_auth: AuthRequired) -> dict[str, Any]:
+    """Return the full wiring topology (nodes + edges) and a validation report."""
+    entities = await run_in_threadpool(_gather_entities)
+    return build_topology(entities)
+
+
+@router.get("/api/v1/graph/dependents/{kind}/{entity_id}", tags=["Graph"])
+async def get_graph_dependents(kind: str, entity_id: str, _auth: AuthRequired) -> dict[str, Any]:
+    """Return every entity that references ``(kind, entity_id)``."""
+    if kind not in ENTITY_KINDS:
+        raise HTTPException(status_code=404, detail=f"Unknown entity kind: {kind}")
+    entities = await run_in_threadpool(_gather_entities)
+    return {"dependents": find_dependents(entities, kind, entity_id)}
+
+
+@router.post("/api/v1/graph/validate-connection", tags=["Graph"])
+async def validate_graph_connection(
+    body: ConnectionValidationRequest, _auth: AuthRequired
+) -> dict[str, Any]:
+    """Validate a proposed wiring edit (existence + source kind + no cycle).
+
+    The graph editor calls this before persisting a drag-connect so it can
+    refuse edits that would dangle a reference or create a dependency loop.
+    """
+    entities = await run_in_threadpool(_gather_entities)
+    ok, error = validate_connection(
+        entities, body.target_kind, body.target_id, body.field, body.source_id
+    )
+    return {"ok": ok, "error": error}
+
+
+# ── Subgraph duplication (server-side blueprint instantiate) ─────────────────
+# Only these kinds are cloned. They carry no inline secrets — they *reference*
+# shared secret-bearing entities (devices, HA sources, HTTP endpoints) by id,
+# and those are NOT cloned — and they have no hardware identity to conflict
+# over. Output targets, automations, devices and integrations are out of scope.
+_DUPLICABLE_KINDS: tuple[str, ...] = ("value_source", "color_strip_source")
+_MAX_DUPLICATE = 200
+
+
+class DuplicateRequest(BaseModel):
+    """Duplicate a selected subgraph of value / colour-strip sources."""
+
+    node_ids: list[str] = Field(..., min_length=1, max_length=_MAX_DUPLICATE)
+    name_suffix: str = Field(default=" (copy)", max_length=40)
+
+
+def _unique_name(existing: set[str], desired: str) -> str:
+    """A name not already in ``existing`` (appends ' 2', ' 3', … on collision)."""
+    if desired not in existing:
+        return desired
+    i = 2
+    while f"{desired} {i}" in existing:
+        i += 1
+    return f"{desired} {i}"
+
+
+def _duplicate_subgraph(node_ids: list[str], name_suffix: str) -> dict[str, Any]:
+    """Deep-clone selected value/colour-strip sources with new ids, rewiring
+    references that point *within* the selection (shared deps are left alone)."""
+    # Index every duplicable entity by id → (kind, store, model); track names.
+    index: dict[str, tuple[str, Any, Any]] = {}
+    existing_names: dict[str, set[str]] = {}
+    for kind in _DUPLICABLE_KINDS:
+        try:
+            store = _KIND_STORES[kind]()
+            models = store.get_all()
+        except Exception as exc:  # noqa: BLE001 — a failing store must not 500 the request
+            logger.warning("graph.duplicate: store for %s unavailable: %s", kind, exc)
+            continue
+        names = existing_names.setdefault(kind, set())
+        for m in models:
+            mid = getattr(m, "id", None)
+            mname = getattr(m, "name", None)
+            if isinstance(mname, str):
+                names.add(mname)
+            if isinstance(mid, str) and mid:
+                index[mid] = (kind, store, m)
+
+    selected: list[str] = []
+    skipped: list[dict[str, str]] = []
+    for nid in dict.fromkeys(node_ids):  # de-dupe, preserve order
+        if nid in index:
+            selected.append(nid)
+        else:
+            skipped.append(
+                {"id": nid, "reason": "only value and colour-strip sources can be duplicated"}
+            )
+
+    # Pass 1 — create clones; their refs still point at the originals (valid).
+    id_map: dict[str, str] = {}
+    created: list[dict[str, str]] = []
+    clones: list[tuple[str, Any, str]] = []
+    for old_id in selected:
+        kind, store, model = index[old_id]
+        base = (getattr(model, "name", None) or old_id) + name_suffix
+        name = _unique_name(existing_names[kind], base)
+        existing_names[kind].add(name)
+        try:
+            new = store.clone(old_id, name)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("graph.duplicate: clone of %s %s failed: %s", kind, old_id, exc)
+            skipped.append({"id": old_id, "reason": f"clone failed: {exc}"})
+            continue
+        id_map[old_id] = new.id
+        created.append({"id": new.id, "kind": kind, "name": new.name})
+        clones.append((kind, store, new.id))
+
+    # Pass 2 — rewrite references that point within the cloned set.
+    warnings: list[dict[str, str]] = []
+    for kind, store, new_id in clones:
+        clone = serialize_entity(store.get(new_id))
+        changed_roots: set[str] = set()
+        for cf in schema_for_kind(kind):
+            if remap_refs(clone, cf.field, id_map):
+                changed_roots.add(cf.field.split(".", 1)[0].removesuffix("[]"))
+        if not changed_roots:
+            continue
+        # `clone` is the FULL serialized entity, so each changed root carries a
+        # complete, structurally-intact value (the whole `layers` list / bindable
+        # dict) that ``update_source`` replaces or merges wholesale. (Within the
+        # duplicable set the only roots that change are scalar ids, `layers` and
+        # bindable slots — never a partially-built nested object.)
+        updates = {root: clone[root] for root in changed_roots if root in clone}
+        try:
+            store.update_source(new_id, **updates)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("graph.duplicate: ref remap of %s failed: %s", new_id, exc)
+            warnings.append({"id": new_id, "reason": f"reference remap failed: {exc}"})
+
+    # Safety net — a clone must never still reference an OLD (in-selection) id.
+    for kind, store, new_id in clones:
+        clone = serialize_entity(store.get(new_id))
+        for cf in schema_for_kind(kind):
+            if any(ref in id_map for ref in extract_refs(clone, cf.field)):
+                warnings.append({"id": new_id, "reason": f"unremapped reference at {cf.field}"})
+
+    return {"id_map": id_map, "created": created, "skipped": skipped, "warnings": warnings}
+
+
+@router.post("/api/v1/graph/duplicate", tags=["Graph"])
+async def duplicate_subgraph(body: DuplicateRequest, _auth: AuthRequired) -> dict[str, Any]:
+    """Deep-clone the selected value/colour-strip sources (new ids, wiring remapped).
+
+    References that point *within* the selection are rewired to the new clones;
+    references to entities outside it (devices, HA sources, …) stay shared with
+    the originals. Only value and colour-strip sources are cloned — they carry no
+    inline secrets — so any other kind in the selection is reported in ``skipped``.
+    """
+    return await run_in_threadpool(_duplicate_subgraph, body.node_ids, body.name_suffix)

server/src/ledgrab/api/routes/output_targets.py

@@ -49,6 +49,8 @@ from ledgrab.storage.value_source_store import ValueSourceStore
 from ledgrab.utils import get_logger
 from ledgrab.storage.base_store import EntityNotFoundError
 
+from ._mqtt_validation import validate_mqtt_source_exists
+
 logger = get_logger(__name__)
 
 router = APIRouter()
@@ -68,6 +70,8 @@ def _led_target_to_response(target: WledOutputTarget) -> LedOutputTargetResponse
         min_brightness_threshold=target.min_brightness_threshold.to_dict(),
         adaptive_fps=target.adaptive_fps,
         protocol=target.protocol,
+        max_milliamps=target.max_milliamps,
+        milliamps_per_led=target.milliamps_per_led,
         description=target.description,
         tags=target.tags,
         icon=getattr(target, "icon", "") or "",
@@ -270,16 +274,6 @@ def _validate_device_exists(device_store: DeviceStore, device_id: str) -> None:
         raise HTTPException(status_code=422, detail=f"Device {device_id} not found")
 
 
-def _validate_mqtt_source_exists(mqtt_store: MQTTSourceStore, mqtt_source_id: str) -> None:
-    """Ensure the referenced MQTT source exists. Empty id is allowed (unconfigured)."""
-    if not mqtt_source_id:
-        return
-    try:
-        mqtt_store.get(mqtt_source_id)
-    except (ValueError, EntityNotFoundError):
-        raise HTTPException(status_code=422, detail=f"MQTT source {mqtt_source_id} not found")
-
-
 @router.post(
     "/api/v1/output-targets", response_model=OutputTargetResponse, tags=["Targets"], status_code=201
 )
@@ -310,6 +304,8 @@ async def create_target(
                     min_brightness_threshold=data.min_brightness_threshold,
                     adaptive_fps=data.adaptive_fps,
                     protocol=data.protocol,
+                    max_milliamps=data.max_milliamps,
+                    milliamps_per_led=data.milliamps_per_led,
                 )
             case HALightOutputTargetCreate():
                 if data.source_kind == "color_vs":
@@ -333,7 +329,7 @@ async def create_target(
             case Z2MLightOutputTargetCreate():
                 if data.source_kind == "color_vs":
                     _validate_color_value_source(value_source_store, data.color_value_source_id)
-                _validate_mqtt_source_exists(mqtt_store, data.mqtt_source_id)
+                validate_mqtt_source_exists(mqtt_store, data.mqtt_source_id)
                 target = target_store.create_z2m_light_target(
                     name=data.name,
                     description=data.description,
@@ -472,6 +468,8 @@ async def update_target(
                     min_brightness_threshold=data.min_brightness_threshold,
                     adaptive_fps=data.adaptive_fps,
                     protocol=data.protocol,
+                    max_milliamps=data.max_milliamps,
+                    milliamps_per_led=data.milliamps_per_led,
                 )
                 css_changed = data.color_strip_source_id is not None
                 brightness_changed = data.brightness is not None
@@ -484,6 +482,8 @@ async def update_target(
                         data.min_brightness_threshold,
                         data.adaptive_fps,
                         data.brightness,
+                        data.max_milliamps,
+                        data.milliamps_per_led,
                     )
                 )
                 device_changed = data.device_id is not None
@@ -540,7 +540,7 @@ async def update_target(
                     )
                     _validate_color_value_source(value_source_store, effective_id)
                 if data.mqtt_source_id:
-                    _validate_mqtt_source_exists(mqtt_store, data.mqtt_source_id)
+                    validate_mqtt_source_exists(mqtt_store, data.mqtt_source_id)
                 target = target_store.update_z2m_light_target(
                     target_id,
                     name=data.name,

server/src/ledgrab/api/routes/snapshot.py

@@ -0,0 +1,201 @@
+"""Aggregated snapshot endpoint for low-overhead polling clients.
+
+Returns, in a single response, everything the Home Assistant integration's
+coordinator needs per poll: all output targets with processing state + metrics,
+all devices with brightness, the color-strip / value-source / scene-preset /
+sync-clock lists, and the system block (performance, health, update).
+
+This collapses the integration's previous ~2N+M request fan-out (per-target
+``/state`` + ``/metrics`` and per-device ``/brightness``) into one round trip.
+
+The handler delegates to the existing list/batch route handlers so the response
+sub-shapes stay byte-identical to the individual endpoints — no shaping logic is
+duplicated here.
+
+Callers that don't need the whole payload can pass ``?include=`` with a
+comma-separated subset of section names (the response keys). Omitting it returns
+every section. Gating is per section, so an excluded section also skips its
+server-side work — dropping ``device_brightness`` avoids cold-cache hardware
+probes, and dropping ``system`` skips the (blocking) NVML performance query.
+"""
+
+import asyncio
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.concurrency import run_in_threadpool
+
+from ledgrab.api.auth import AuthRequired
+from ledgrab.api.dependencies import (
+    get_color_strip_store,
+    get_device_store,
+    get_output_target_store,
+    get_processor_manager,
+    get_scene_preset_store,
+    get_sync_clock_manager,
+    get_sync_clock_store,
+    get_update_service,
+    get_value_source_store,
+)
+from ledgrab.api.schemas.update import UpdateStatusResponse
+from ledgrab.utils import get_logger
+
+from .color_strip_sources.crud import list_color_strip_sources
+from .devices import list_devices, resolve_device_brightness
+from .output_targets import batch_target_metrics, batch_target_states, list_targets
+from .scene_presets import list_scene_presets
+from .sync_clocks import list_sync_clocks
+from .system import get_system_performance, health_check
+from .update import get_update_status
+from .value_sources import list_value_sources
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+# Selectable snapshot sections — these are exactly the response top-level keys.
+SNAPSHOT_SECTIONS = (
+    "targets",
+    "target_states",
+    "target_metrics",
+    "devices",
+    "device_brightness",
+    "css_sources",
+    "value_sources",
+    "scene_presets",
+    "sync_clocks",
+    "system",
+)
+_SECTION_SET = frozenset(SNAPSHOT_SECTIONS)
+
+
+def _resolve_sections(include: str | None) -> frozenset[str]:
+    """Validate the ``include`` query param into the set of sections to emit.
+
+    ``None``/empty → every section. Unknown names are rejected with 422 so a
+    typo fails loudly instead of silently returning a smaller payload.
+    """
+    if not include:
+        return _SECTION_SET
+    requested = {part.strip() for part in include.split(",") if part.strip()}
+    unknown = requested - _SECTION_SET
+    if unknown:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"Unknown snapshot section(s): {', '.join(sorted(unknown))}. "
+                f"Valid sections: {', '.join(SNAPSHOT_SECTIONS)}."
+            ),
+        )
+    return frozenset(requested)
+
+
+async def _safe_section(awaitable, label: str):
+    """Await a section, degrading to ``None`` on failure instead of 500-ing.
+
+    The snapshot is a resilience-oriented poll surface: one failing section
+    (e.g. NVML performance probing) must not fail the whole response. This
+    preserves the per-section fault isolation the HA coordinator relied on
+    before these calls were merged into one request — the coordinator already
+    tolerates a ``None`` section.
+    """
+    try:
+        return await awaitable
+    except Exception:
+        logger.warning("snapshot: section %r failed, returning null", label, exc_info=True)
+        return None
+
+
+async def _update_status_model(_auth, update_service) -> UpdateStatusResponse:
+    """Fetch update status and coerce it through the response model.
+
+    The standalone ``/system/update/status`` endpoint declares
+    ``response_model=UpdateStatusResponse``; coercing here keeps the snapshot's
+    ``system.update`` field identical to that endpoint rather than emitting the
+    service's raw dict unfiltered.
+    """
+    raw = await get_update_status(_auth, update_service)
+    return UpdateStatusResponse.model_validate(raw)
+
+
+@router.get("/api/v1/snapshot", tags=["Snapshot"])
+async def get_snapshot(
+    request: Request,
+    _auth: AuthRequired,
+    include: str | None = Query(
+        None,
+        description=(
+            "Comma-separated subset of sections to include. Omit for all. "
+            "Valid: " + ", ".join(SNAPSHOT_SECTIONS)
+        ),
+    ),
+    manager=Depends(get_processor_manager),
+    target_store=Depends(get_output_target_store),
+    device_store=Depends(get_device_store),
+    css_store=Depends(get_color_strip_store),
+    value_store=Depends(get_value_source_store),
+    preset_store=Depends(get_scene_preset_store),
+    clock_store=Depends(get_sync_clock_store),
+    clock_manager=Depends(get_sync_clock_manager),
+    update_service=Depends(get_update_service),
+) -> dict[str, Any]:
+    """Return the full poll payload (or a requested subset) in one response.
+
+    Shape (a key is present only when its section is requested)::
+
+        {
+          "targets": [<OutputTargetResponse>, ...],
+          "target_states": {target_id: <state>, ...},
+          "target_metrics": {target_id: <metrics>, ...},
+          "devices": [<DeviceResponse>, ...],
+          "device_brightness": {device_id: int | null, ...},
+          "css_sources": [...],
+          "value_sources": [...],
+          "scene_presets": [...],
+          "sync_clocks": [...],
+          "system": {"performance": {...}, "health": {...}, "update": {...}}
+        }
+    """
+    sections = _resolve_sections(include)
+    result: dict[str, Any] = {}
+
+    if "targets" in sections:
+        result["targets"] = (await list_targets(_auth, target_store)).targets
+    if "target_states" in sections:
+        result["target_states"] = (await batch_target_states(_auth, manager))["states"]
+    if "target_metrics" in sections:
+        result["target_metrics"] = (await batch_target_metrics(_auth, manager))["metrics"]
+    if "devices" in sections:
+        result["devices"] = (await list_devices(_auth, device_store)).devices
+    if "device_brightness" in sections:
+        device_models = device_store.get_all_devices()
+        brightness_values = await asyncio.gather(
+            *(resolve_device_brightness(d, manager) for d in device_models),
+            return_exceptions=True,
+        )
+        result["device_brightness"] = {
+            model.id: (None if isinstance(value, BaseException) else value)
+            for model, value in zip(device_models, brightness_values)
+        }
+    if "css_sources" in sections:
+        css = await list_color_strip_sources(_auth, css_store, manager)
+        result["css_sources"] = css.sources
+    if "value_sources" in sections:
+        result["value_sources"] = (await list_value_sources(_auth, None, value_store)).sources
+    if "scene_presets" in sections:
+        result["scene_presets"] = (await list_scene_presets(_auth, preset_store)).presets
+    if "sync_clocks" in sections:
+        clocks = await list_sync_clocks(_auth, clock_store, clock_manager)
+        result["sync_clocks"] = clocks.clocks
+    if "system" in sections:
+        result["system"] = {
+            "performance": await _safe_section(
+                run_in_threadpool(get_system_performance, _auth), "system.performance"
+            ),
+            "health": await _safe_section(health_check(request), "system.health"),
+            "update": await _safe_section(
+                _update_status_model(_auth, update_service), "system.update"
+            ),
+        }
+
+    return result

server/src/ledgrab/api/routes/system.py

@@ -39,8 +39,11 @@ from ledgrab.api.schemas.system import (
     DisplayListResponse,
     GpuInfo,
     HealthResponse,
+    InstalledAppItem,
+    InstalledAppsResponse,
     PerformanceResponse,
     ProcessListResponse,
+    SystemInfoResponse,
     VersionResponse,
 )
 from ledgrab.config import get_config, is_demo_mode
@@ -278,6 +281,52 @@ async def get_running_processes(_: AuthRequired):
         raise HTTPException(status_code=500, detail="Internal server error")
 
 
+@router.get(
+    "/api/v1/system/installed-apps",
+    response_model=InstalledAppsResponse,
+    tags=["Config"],
+)
+def get_installed_apps(_: AuthRequired):
+    """List launchable apps for the application-rule app picker (Android only).
+
+    Returns launchable apps (package + human label) on Android, where the
+    foreground-app automation rule matches package names. Returns an empty list
+    on desktop, where the process picker (``/system/processes``) is used instead.
+    Sync ``def`` so FastAPI runs the (potentially blocking) bridge call in a
+    thread pool.
+    """
+    from ledgrab.core.automations import platform_detector as pd
+
+    try:
+        apps = pd.list_installed_apps()
+        items = [InstalledAppItem(package=a["package"], label=a["label"]) for a in apps]
+        return InstalledAppsResponse(apps=items, count=len(items))
+    except Exception as e:
+        logger.error("Failed to list installed apps: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.get("/api/v1/system/info", response_model=SystemInfoResponse, tags=["Info"])
+def get_system_info(_: AuthRequired):
+    """Platform capability signal for the automation editor.
+
+    Tells the frontend whether the server is on Android (so the application-rule
+    editor uses the launchable-app picker + package matching and surfaces the
+    Usage-Access banner) vs desktop (process picker + process names), and whether
+    Usage Access is currently granted. Sync ``def`` so the bridge call runs in a
+    thread pool.
+    """
+    from ledgrab.core.automations import platform_detector as pd
+    from ledgrab.utils.platform import is_android
+
+    android = is_android()
+    return SystemInfoResponse(
+        is_android=android,
+        app_match_kind="package" if android else "process",
+        usage_access_granted=(pd.has_usage_access() if android else True),
+    )
+
+
 @router.get(
     "/api/v1/system/performance",
     response_model=PerformanceResponse,

server/src/ledgrab/api/routes/value_sources.py

@@ -4,6 +4,7 @@ import asyncio
 from typing import Annotated
 
 from fastapi import APIRouter, Body, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel, Field
 
 from ledgrab.api.auth import AuthRequired
 from ledgrab.api.dependencies import (
@@ -27,6 +28,8 @@ from ledgrab.api.schemas.value_sources import (
     StaticColorValueSourceResponse,
     StaticValueSourceResponse,
     SystemMetricsValueSourceResponse,
+    TemplateInput,
+    TemplateValueSourceResponse,
     ValueSourceCreate,
     ValueSourceListResponse,
     ValueSourceResponse,
@@ -46,6 +49,7 @@ from ledgrab.storage.value_source import (
     StaticColorValueSource,
     StaticValueSource,
     SystemMetricsValueSource,
+    TemplateValueSource,
     ValueSource,
 )
 from ledgrab.storage.value_source_store import ValueSourceStore
@@ -170,6 +174,7 @@ _RESPONSE_MAP = {
         min_ha_value=s.min_ha_value,
         max_ha_value=s.max_ha_value,
         smoothing=s.smoothing,
+        normalize=s.normalize,
     ),
     GradientMapValueSource: lambda s: GradientMapValueSourceResponse(
         id=s.id,
@@ -214,6 +219,7 @@ _RESPONSE_MAP = {
         sensor_label=s.sensor_label,
         poll_interval=s.poll_interval,
         smoothing=s.smoothing,
+        normalize=s.normalize,
     ),
     HTTPValueSource: lambda s: HTTPValueSourceResponse(
         id=s.id,
@@ -230,6 +236,23 @@ _RESPONSE_MAP = {
         min_value=s.min_value,
         max_value=s.max_value,
         smoothing=s.smoothing,
+        normalize=s.normalize,
+    ),
+    TemplateValueSource: lambda s: TemplateValueSourceResponse(
+        id=s.id,
+        name=s.name,
+        description=s.description,
+        tags=s.tags,
+        icon=getattr(s, "icon", "") or "",
+        icon_color=getattr(s, "icon_color", "") or "",
+        created_at=s.created_at,
+        updated_at=s.updated_at,
+        template=s.template,
+        inputs=[
+            TemplateInput(name=i["name"], value_source_id=i["value_source_id"]) for i in s.inputs
+        ],
+        default_value=s.default_value,
+        eval_interval=s.eval_interval,
     ),
 }
 
@@ -395,6 +418,13 @@ async def delete_value_source(
                 if getattr(target, "brightness_value_source_id", "") == source_id:
                     raise ValueError(f"Cannot delete: referenced by target '{target.name}'")
 
+        # Check if any other value source (template / gradient_map) references it.
+        referencing = store.find_referencing_sources(source_id)
+        if referencing:
+            raise ValueError(
+                "Cannot delete: referenced by value source(s) " + ", ".join(referencing)
+            )
+
         store.delete_source(source_id)
         fire_entity_event("value_source", "deleted", source_id)
     except EntityNotFoundError as e:
@@ -404,6 +434,121 @@ async def delete_value_source(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+class ValidateTemplateRequest(BaseModel):
+    """Request body for the advisory template-validation endpoint."""
+
+    template: str = Field(description="Jinja2 expression to validate", max_length=2000)
+    inputs: list[TemplateInput] = Field(default_factory=list, description="Named input bindings")
+    id: str | None = Field(None, description="Source id when editing (enables cycle detection)")
+
+
+@router.post("/api/v1/value-sources/validate-template", tags=["Value Sources"])
+async def validate_template_value_source(
+    payload: ValidateTemplateRequest,
+    _auth: AuthRequired,
+    store: ValueSourceStore = Depends(get_value_source_store),
+):
+    """Validate a template expression + inputs without persisting anything.
+
+    Advisory: always returns HTTP 200 with ``{valid, error, errors, warnings,
+    variables}``. Powers the live editor validator (which must run before a
+    source exists), reusing the exact factory/store validation so the client and
+    server can never disagree. ``errors`` are blocking (save disabled);
+    ``warnings`` are non-blocking (e.g. unknown/unbound inputs — create is
+    lenient about those).
+    """
+    from ledgrab.utils.template_expr import (
+        TemplateValidationError,
+        extract_variables,
+        validate_input_name,
+        validate_template_expression,
+    )
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # 1) Expression compiles and is safe (cost-guarded).
+    try:
+        validate_template_expression(payload.template)
+    except TemplateValidationError as e:
+        errors.append(str(e))
+
+    # 2) Input names valid / unique / non-reserved (blocking).
+    seen: set[str] = set()
+    for inp in payload.inputs:
+        try:
+            validate_input_name(inp.name)
+        except TemplateValidationError as e:
+            errors.append(str(e))
+            continue
+        if inp.name in seen:
+            errors.append(f"duplicate input name: {inp.name}")
+        seen.add(inp.name)
+
+    # 3) Referenced sources exist (non-blocking warning — create is lenient).
+    missing = [
+        inp.value_source_id
+        for inp in payload.inputs
+        if inp.value_source_id and not _source_exists(store, inp.value_source_id)
+    ]
+    if missing:
+        warnings.append("unknown value source(s): " + ", ".join(sorted(set(missing))))
+
+    # 4) Variables referenced in the expression but not bound to an input
+    # (blocking): at runtime they raise UndefinedError, so the template would
+    # silently always return default_value. This is almost always a typo, so
+    # flag it as an error rather than letting "valid" mislead the user.
+    used = set(extract_variables(payload.template))
+    undeclared = used - seen
+    if undeclared:
+        errors.append("unbound variable(s): " + ", ".join(sorted(undeclared)))
+
+    # 5) Cycle check when editing an existing source (blocking).
+    if payload.id:
+        child_ids = [i.value_source_id for i in payload.inputs if i.value_source_id]
+        try:
+            store.validate_nesting(payload.id, child_ids)
+        except ValueError as e:
+            errors.append(str(e))
+
+    return {
+        "valid": not errors,
+        "error": errors[0] if errors else None,
+        "errors": errors,
+        "warnings": warnings,
+        "variables": extract_variables(payload.template),
+    }
+
+
+def _source_exists(store: ValueSourceStore, source_id: str) -> bool:
+    try:
+        store.get_source(source_id)
+        return True
+    except Exception:
+        return False
+
+
+# Per-stream (min, max) attribute pairs for the normalization range, so the
+# preview can show where the raw value maps. Attribute names differ per stream
+# type (historical), so probe each pair rather than assume one.
+_RAW_RANGE_ATTRS: tuple[tuple[str, str], ...] = (
+    ("_min_ha", "_max_ha"),  # HAEntityValueStream
+    ("_min_value", "_max_value"),  # HTTPValueStream
+    ("_min_val", "_max_val"),  # SystemMetricsValueStream
+    ("_min_game", "_max_game"),  # GameEventValueStream
+)
+
+
+def _stream_raw_range(stream) -> list | None:
+    """Return ``[min, max]`` for the stream's normalization range, or None."""
+    for lo_attr, hi_attr in _RAW_RANGE_ATTRS:
+        lo = getattr(stream, lo_attr, None)
+        hi = getattr(stream, hi_attr, None)
+        if isinstance(lo, (int, float)) and isinstance(hi, (int, float)):
+            return [lo, hi]
+    return None
+
+
 # ===== REAL-TIME VALUE SOURCE TEST WEBSOCKET =====
 
 
@@ -467,10 +612,22 @@ async def test_value_source_ws(
                 msg["input_value"] = round(stream.get_input_value(), 4)
             if hasattr(stream, "get_raw_value"):
                 raw = stream.get_raw_value()
-                if raw is not None:
+                if isinstance(raw, bool):
-                    msg["raw_value"] = round(raw, 4)
+                    # bool is a subclass of int — send as-is (don't coerce/round).
-                    if hasattr(stream, "_min_ha"):
+                    msg["raw_value"] = raw
-                        msg["raw_range"] = [stream._min_ha, stream._max_ha]
+                elif isinstance(raw, (int, float)):
+                    msg["raw_value"] = round(float(raw), 4)
+                elif raw is not None:
+                    # Non-numeric raw (e.g. an HTTP string payload) — send verbatim
+                    # rather than crash the socket on round().
+                    msg["raw_value"] = raw
+                rng = _stream_raw_range(stream)
+                if rng is not None:
+                    msg["raw_range"] = rng
+            # Tell the client whether this source is currently normalizing, so the
+            # preview can render the value as a fraction vs a clamped passthrough.
+            if hasattr(stream, "_normalize_enabled"):
+                msg["normalized"] = bool(stream._normalize_enabled)
             await websocket.send_json(msg)
             await asyncio.sleep(0.05)
     except WebSocketDisconnect:

server/src/ledgrab/api/schemas/automations.py

@@ -11,9 +11,21 @@ class RuleSchema(BaseModel):
 
     rule_type: str = Field(description="Rule type discriminator (e.g. 'application')")
     # Application rule fields
-    apps: List[str] | None = Field(None, description="Process names (for application rule)")
+    apps: List[str] | None = Field(
+        None,
+        description=(
+            "App identifiers for the application rule. Platform-specific and not "
+            "portable: process names on Windows (e.g. 'chrome.exe'), package names "
+            "on Android (e.g. 'com.android.chrome'). Matched case-insensitively."
+        ),
+    )
     match_type: str | None = Field(
-        None, description="'running' or 'topmost' (for application rule)"
+        None,
+        description=(
+            "'running', 'topmost', 'fullscreen', or 'topmost_fullscreen' (application "
+            "rule). On Android only the foreground app is detectable, so all values "
+            "behave as 'foreground'."
+        ),
     )
     # Time-of-day rule fields
     start_time: str | None = Field(None, description="Start time HH:MM (for time_of_day rule)")

server/src/ledgrab/api/schemas/devices.py

@@ -131,6 +131,11 @@ class DeviceCreate(BaseModel):
         None,
         description="Govee AES key (hex) — required for encrypted Govee firmware",
     )
+    # MQTT (multi-broker) field
+    mqtt_source_id: str | None = Field(
+        None,
+        description="MQTT source (broker) ID for device_type=mqtt. Empty = first available broker.",
+    )
     default_css_processing_template_id: str | None = Field(
         None, description="Default color strip processing template ID"
     )
@@ -217,6 +222,9 @@ class DeviceUpdate(BaseModel):
     ble_govee_key: str | None = Field(
         None, description="Govee AES key (hex) — required for encrypted Govee firmware"
     )
+    mqtt_source_id: str | None = Field(
+        None, description="MQTT source (broker) ID for device_type=mqtt"
+    )
     default_css_processing_template_id: str | None = Field(
         None, description="Default color strip processing template ID"
     )
@@ -436,6 +444,9 @@ class DeviceResponse(BaseModel):
     ble_govee_key: str = Field(
         default="", description="Govee AES key (hex) — required for encrypted Govee firmware"
     )
+    mqtt_source_id: str = Field(
+        default="", description="MQTT source (broker) ID for device_type=mqtt"
+    )
     default_css_processing_template_id: str = Field(
         default="", description="Default color strip processing template ID"
     )

server/src/ledgrab/api/schemas/output_targets.py

@@ -92,6 +92,10 @@ class LedOutputTargetResponse(_OutputTargetResponseBase):
         default=False, description="Auto-reduce FPS when device is unresponsive"
     )
     protocol: str = Field(default="ddp", description="Send protocol (ddp or http)")
+    max_milliamps: int = Field(
+        default=0, description="ABL: PSU current budget in mA (0 = unlimited)"
+    )
+    milliamps_per_led: int = Field(default=55, description="ABL: full-white draw of one LED in mA")
 
 
 class HALightOutputTargetResponse(_OutputTargetResponseBase):
@@ -236,6 +240,18 @@ class LedOutputTargetCreate(_OutputTargetCreateBase):
         pattern="^(ddp|http)$",
         description="Send protocol: ddp (UDP) or http (JSON API)",
     )
+    max_milliamps: int = Field(
+        default=0,
+        ge=0,
+        le=200000,
+        description="Automatic brightness limiting: PSU current budget in mA (0 = unlimited)",
+    )
+    milliamps_per_led: int = Field(
+        default=55,
+        ge=1,
+        le=200,
+        description="ABL: estimated full-white draw of a single LED, in mA",
+    )
 
 
 class HALightOutputTargetCreate(_OutputTargetCreateBase):
@@ -372,6 +388,12 @@ class LedOutputTargetUpdate(_OutputTargetUpdateBase):
     protocol: str | None = Field(
         None, pattern="^(ddp|http)$", description="Send protocol: ddp (UDP) or http (JSON API)"
     )
+    max_milliamps: int | None = Field(
+        None, ge=0, le=200000, description="ABL: PSU current budget in mA (0 = unlimited)"
+    )
+    milliamps_per_led: int | None = Field(
+        None, ge=1, le=200, description="ABL: full-white draw of one LED in mA"
+    )
 
 
 class HALightOutputTargetUpdate(_OutputTargetUpdateBase):

server/src/ledgrab/api/schemas/system.py

@@ -68,6 +68,42 @@ class ProcessListResponse(BaseModel):
     count: int = Field(description="Number of unique processes")
 
 
+class InstalledAppItem(BaseModel):
+    """A launchable Android app, for the automation app picker."""
+
+    package: str = Field(description="Android package name, e.g. 'com.netflix.mediaclient'")
+    label: str = Field(description="Human-readable app label, e.g. 'Netflix'")
+
+
+class InstalledAppsResponse(BaseModel):
+    """Launchable apps for the application-rule picker (Android only; empty elsewhere)."""
+
+    apps: List[InstalledAppItem] = Field(description="Launchable apps, sorted by label")
+    count: int = Field(description="Number of apps")
+
+
+class SystemInfoResponse(BaseModel):
+    """Platform capability signal for the frontend (automation editor).
+
+    Lets the application-rule editor choose the right app source and matching
+    semantics per platform, and surface the Usage-Access permission state.
+    """
+
+    is_android: bool = Field(description="True when the server runs on Android (Chaquopy)")
+    app_match_kind: Literal["process", "package"] = Field(
+        description=(
+            "What ApplicationRule.apps values represent: 'process' names on desktop, "
+            "'package' names on Android."
+        )
+    )
+    usage_access_granted: bool = Field(
+        description=(
+            "Android: whether PACKAGE_USAGE_STATS (Usage Access) is granted, gating "
+            "foreground-app detection. Always True (not applicable) off-Android."
+        )
+    )
+
+
 class GpuInfo(BaseModel):
     """GPU performance information."""
 

server/src/ledgrab/api/schemas/value_sources.py

@@ -10,6 +10,17 @@ from pydantic import BaseModel, Discriminator, Field, Tag
 # =====================================================================
 
 
+class TemplateInput(BaseModel):
+    """A single ``{name -> value_source_id}`` binding for a template source."""
+
+    name: str = Field(
+        description="Variable name used in the expression (valid identifier)",
+        min_length=1,
+        max_length=64,
+    )
+    value_source_id: str = Field("", description="Bound value source ID (empty = unbound)")
+
+
 class _ValueSourceResponseBase(BaseModel):
     """Shared fields for all value source responses."""
 
@@ -120,6 +131,9 @@ class HAEntityValueSourceResponse(_ValueSourceResponseBase):
     min_ha_value: float = Field(description="Raw HA value mapped to output 0.0")
     max_ha_value: float = Field(description="Raw HA value mapped to output 1.0")
     smoothing: float = Field(description="EMA smoothing factor (0.0-1.0)")
+    normalize: bool = Field(
+        description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
 
 
 class GradientMapValueSourceResponse(_ValueSourceResponseBase):
@@ -149,6 +163,9 @@ class SystemMetricsValueSourceResponse(_ValueSourceResponseBase):
     sensor_label: str = Field(description="Sensor label for cpu_temp/fan_speed")
     poll_interval: float = Field(description="Seconds between reads")
     smoothing: float = Field(description="EMA smoothing factor (0.0-1.0)")
+    normalize: bool = Field(
+        description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
 
 
 class HTTPValueSourceResponse(_ValueSourceResponseBase):
@@ -160,6 +177,22 @@ class HTTPValueSourceResponse(_ValueSourceResponseBase):
     min_value: float = Field(description="Raw value mapped to output 0.0")
     max_value: float = Field(description="Raw value mapped to output 1.0")
     smoothing: float = Field(description="EMA smoothing factor (0.0-1.0)")
+    normalize: bool = Field(
+        description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
+
+
+class TemplateValueSourceResponse(_ValueSourceResponseBase):
+    source_type: Literal["template"] = "template"
+    return_type: Literal["float"] = "float"
+    template: str = Field(description="Jinja2 expression")
+    inputs: List[TemplateInput] = Field(
+        default_factory=list, description="Named value-source bindings"
+    )
+    default_value: float = Field(description="Fallback when the expression errors (0.0-1.0)")
+    eval_interval: float | None = Field(
+        None, description="Re-eval throttle in seconds (None/0 = every poll)"
+    )
 
 
 ValueSourceResponse = Annotated[
@@ -176,7 +209,8 @@ ValueSourceResponse = Annotated[
     | Annotated[GradientMapValueSourceResponse, Tag("gradient_map")]
     | Annotated[CSSExtractValueSourceResponse, Tag("css_extract")]
     | Annotated[SystemMetricsValueSourceResponse, Tag("system_metrics")]
-    | Annotated[HTTPValueSourceResponse, Tag("http")],
+    | Annotated[HTTPValueSourceResponse, Tag("http")]
+    | Annotated[TemplateValueSourceResponse, Tag("template")],
     Discriminator("source_type"),
 ]
 
@@ -292,6 +326,9 @@ class HAEntityValueSourceCreate(_ValueSourceCreateBase):
     min_ha_value: float = Field(0.0, description="Raw HA value mapped to output 0.0")
     max_ha_value: float = Field(100.0, description="Raw HA value mapped to output 1.0")
     smoothing: float = Field(0.0, description="EMA smoothing (0.0-1.0)", ge=0.0, le=1.0)
+    normalize: bool = Field(
+        True, description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
 
 
 class GradientMapValueSourceCreate(_ValueSourceCreateBase):
@@ -318,6 +355,9 @@ class SystemMetricsValueSourceCreate(_ValueSourceCreateBase):
     sensor_label: str = Field("", description="Sensor label for cpu_temp/fan_speed")
     poll_interval: float = Field(1.0, description="Poll interval in seconds", ge=0.1, le=60.0)
     smoothing: float = Field(0.0, description="EMA smoothing (0.0-1.0)", ge=0.0, le=1.0)
+    normalize: bool = Field(
+        True, description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
 
 
 class HTTPValueSourceCreate(_ValueSourceCreateBase):
@@ -328,6 +368,30 @@ class HTTPValueSourceCreate(_ValueSourceCreateBase):
     min_value: float = Field(0.0, description="Raw value mapped to output 0.0")
     max_value: float = Field(100.0, description="Raw value mapped to output 1.0")
     smoothing: float = Field(0.0, description="EMA smoothing (0.0-1.0)", ge=0.0, le=1.0)
+    normalize: bool = Field(
+        True, description="Rescale raw value to [0,1] via min/max; false clamps the raw value as-is"
+    )
+
+
+class TemplateValueSourceCreate(_ValueSourceCreateBase):
+    source_type: Literal["template"] = "template"
+    template: str = Field(
+        description=(
+            "Jinja2 expression (no statements/blocks). Inputs are exposed by name and via "
+            "raw[name]; globals: min, max, abs, round, clamp(x, lo=0, hi=1)."
+        ),
+        min_length=1,
+        max_length=2000,
+    )
+    inputs: List[TemplateInput] = Field(
+        default_factory=list, description="Named value-source bindings"
+    )
+    default_value: float = Field(
+        0.0, description="Fallback when the expression errors (0.0-1.0)", ge=0.0, le=1.0
+    )
+    eval_interval: float | None = Field(
+        None, description="Re-eval throttle in seconds (None/0 = every poll)", ge=0.0
+    )
 
 
 ValueSourceCreate = Annotated[
@@ -344,7 +408,8 @@ ValueSourceCreate = Annotated[
     | Annotated[GradientMapValueSourceCreate, Tag("gradient_map")]
     | Annotated[CSSExtractValueSourceCreate, Tag("css_extract")]
     | Annotated[SystemMetricsValueSourceCreate, Tag("system_metrics")]
-    | Annotated[HTTPValueSourceCreate, Tag("http")],
+    | Annotated[HTTPValueSourceCreate, Tag("http")]
+    | Annotated[TemplateValueSourceCreate, Tag("template")],
     Discriminator("source_type"),
 ]
 
@@ -452,6 +517,9 @@ class HAEntityValueSourceUpdate(_ValueSourceUpdateBase):
     min_ha_value: float | None = Field(None, description="Min HA value")
     max_ha_value: float | None = Field(None, description="Max HA value")
     smoothing: float | None = Field(None, description="EMA smoothing", ge=0.0, le=1.0)
+    normalize: bool | None = Field(
+        None, description="Rescale raw via min/max (false = clamp as-is)"
+    )
 
 
 class GradientMapValueSourceUpdate(_ValueSourceUpdateBase):
@@ -478,6 +546,9 @@ class SystemMetricsValueSourceUpdate(_ValueSourceUpdateBase):
     sensor_label: str | None = Field(None, description="Sensor label")
     poll_interval: float | None = Field(None, description="Poll interval", ge=0.1, le=60.0)
     smoothing: float | None = Field(None, description="EMA smoothing", ge=0.0, le=1.0)
+    normalize: bool | None = Field(
+        None, description="Rescale raw via min/max (false = clamp as-is)"
+    )
 
 
 class HTTPValueSourceUpdate(_ValueSourceUpdateBase):
@@ -488,6 +559,23 @@ class HTTPValueSourceUpdate(_ValueSourceUpdateBase):
     min_value: float | None = Field(None, description="Raw value mapped to 0.0")
     max_value: float | None = Field(None, description="Raw value mapped to 1.0")
     smoothing: float | None = Field(None, description="EMA smoothing", ge=0.0, le=1.0)
+    normalize: bool | None = Field(
+        None, description="Rescale raw via min/max (false = clamp as-is)"
+    )
+
+
+class TemplateValueSourceUpdate(_ValueSourceUpdateBase):
+    source_type: Literal["template"] = "template"
+    template: str | None = Field(
+        None, description="Jinja2 expression", min_length=1, max_length=2000
+    )
+    inputs: List[TemplateInput] | None = Field(None, description="Named value-source bindings")
+    default_value: float | None = Field(
+        None, description="Fallback when the expression errors (0.0-1.0)", ge=0.0, le=1.0
+    )
+    eval_interval: float | None = Field(
+        None, description="Re-eval throttle in seconds (0 = every poll)", ge=0.0
+    )
 
 
 ValueSourceUpdate = Annotated[
@@ -504,7 +592,8 @@ ValueSourceUpdate = Annotated[
     | Annotated[GradientMapValueSourceUpdate, Tag("gradient_map")]
     | Annotated[CSSExtractValueSourceUpdate, Tag("css_extract")]
     | Annotated[SystemMetricsValueSourceUpdate, Tag("system_metrics")]
-    | Annotated[HTTPValueSourceUpdate, Tag("http")],
+    | Annotated[HTTPValueSourceUpdate, Tag("http")]
+    | Annotated[TemplateValueSourceUpdate, Tag("template")],
     Discriminator("source_type"),
 ]
 

server/src/ledgrab/core/audio/__init__.py

@@ -38,6 +38,19 @@ try:
 except ImportError:
     _has_sounddevice = False
 
+# Android playback-capture engine — pure Python (numpy only), but the
+# guard keeps the registration pattern uniform and tolerant of any future
+# import-time dependency.
+try:
+    from ledgrab.core.audio.android_audio_engine import (
+        AndroidAudioEngine,
+        AndroidAudioCaptureStream,
+    )
+
+    _has_android_audio = True
+except ImportError:
+    _has_android_audio = False
+
 from ledgrab.core.audio.demo_engine import DemoAudioEngine, DemoAudioCaptureStream
 
 # Auto-register available engines
@@ -45,6 +58,8 @@ if _has_wasapi:
     AudioEngineRegistry.register(WasapiEngine)
 if _has_sounddevice:
     AudioEngineRegistry.register(SounddeviceEngine)
+if _has_android_audio:
+    AudioEngineRegistry.register(AndroidAudioEngine)
 AudioEngineRegistry.register(DemoAudioEngine)
 
 __all__ = [
@@ -65,3 +80,5 @@ if _has_wasapi:
     __all__ += ["WasapiEngine", "WasapiCaptureStream"]
 if _has_sounddevice:
     __all__ += ["SounddeviceEngine", "SounddeviceCaptureStream"]
+if _has_android_audio:
+    __all__ += ["AndroidAudioEngine", "AndroidAudioCaptureStream"]

server/src/ledgrab/core/audio/android_audio_engine.py

@@ -0,0 +1,229 @@
+"""Android playback-capture audio engine.
+
+Receives PCM pushed from Kotlin (via Chaquopy) through a module-level
+sample queue.  The Kotlin layer captures system playback audio with
+``AudioRecord`` + ``AudioPlaybackCaptureConfiguration`` (reusing the
+app's ``MediaProjection`` token) and calls :func:`push_samples` with
+interleaved float32 PCM for each fixed-size block.
+
+Mirrors the screen-capture bridge
+(``core/capture_engines/mediaprojection_engine.py``): a module-level
+queue plus ``configure`` / ``push_samples`` / ``shutdown`` filled by
+Kotlin, consumed through the standard :class:`AudioCaptureStreamBase`
+interface so :class:`~ledgrab.core.audio.audio_capture.ManagedAudioStream`
+and :class:`~ledgrab.core.audio.analysis.AudioAnalyzer` work unchanged.
+
+This engine is only available when running inside the LedGrab Android
+app, which has set up the sample queue via :func:`configure`.
+"""
+
+import queue
+from typing import Any, Dict, List
+
+import numpy as np
+
+from ledgrab.core.audio.base import (
+    AudioCaptureEngine,
+    AudioCaptureStreamBase,
+    AudioDeviceInfo,
+)
+from ledgrab.utils import get_logger
+from ledgrab.utils.platform import is_android
+
+logger = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Sample queue — the bridge between Kotlin and Python
+# ---------------------------------------------------------------------------
+
+_pcm_queue: "queue.Queue[np.ndarray]" = queue.Queue(maxsize=8)
+_sample_rate = 48000
+_channels = 2
+_chunk_size = 1024
+_active = False
+_frames_received = 0
+
+
+def configure(sample_rate: int, channels: int, chunk_size: int) -> None:
+    """Set the stream format.  Called from Kotlin before frames flow.
+
+    Drains any stale PCM from a previous capture session so the first
+    chunk after a restart is actually current.  ``channels`` /
+    ``sample_rate`` should be the values the Kotlin ``AudioRecord``
+    actually negotiated (which can differ from the requested values,
+    e.g. a stereo request that falls back to mono) — the analyzer keys
+    off these, so they must match the interleaving of pushed samples.
+    """
+    global _sample_rate, _channels, _chunk_size, _active, _frames_received
+    while not _pcm_queue.empty():
+        try:
+            _pcm_queue.get_nowait()
+        except queue.Empty:
+            break
+    _sample_rate = sample_rate
+    _channels = max(1, channels)
+    _chunk_size = max(1, chunk_size)
+    _frames_received = 0
+    _active = True
+    logger.info(
+        "Android audio engine configured: sr=%d channels=%d chunk=%d",
+        _sample_rate,
+        _channels,
+        _chunk_size,
+    )
+
+
+def push_samples(pcm_float32: bytes) -> None:
+    """Push one interleaved float32 PCM block from Kotlin.
+
+    The byte buffer is interpreted as native-endian float32 (Kotlin
+    packs little-endian; all Android ABIs are little-endian).  Drops the
+    oldest queued block if the consumer is slow (non-blocking).
+
+    Defensive framing: the downstream :class:`AudioAnalyzer` reshapes to
+    ``(-1, channels)`` and copies into ``chunk_size``-sized scratch
+    buffers, so it raises on a block whose length is not a whole number
+    of frames or that exceeds ``chunk_size`` frames.  We trim to a whole
+    multiple of ``_channels`` and clamp to ``_chunk_size`` frames so a
+    malformed push can never crash the capture thread.
+    """
+    global _frames_received
+    # np.frombuffer raises if the length isn't a whole number of float32s.
+    # Kotlin always pushes complete blocks, but guard so a malformed buffer is
+    # dropped here rather than surfacing as an exception across the JNI bridge.
+    if len(pcm_float32) % 4 != 0:
+        return
+    samples = np.frombuffer(pcm_float32, dtype=np.float32)
+
+    # Trim to whole frames, then clamp to chunk_size frames.
+    frames = len(samples) // _channels
+    if frames <= 0:
+        return
+    frames = min(frames, _chunk_size)
+    usable = frames * _channels
+
+    # Copy out of the read-only frombuffer view so the queued block owns its
+    # memory.  This lets the Kotlin side push from a reusable buffer (low GC on
+    # low-end TV boxes) without the not-yet-consumed queued block aliasing
+    # bytes Kotlin is about to overwrite.  Mirrors mediaprojection_engine's
+    # push_frame .copy().
+    block = samples[:usable].copy()
+
+    _frames_received += 1
+    if _frames_received == 1 or _frames_received % 100 == 0:
+        logger.info("Android audio: received %d blocks", _frames_received)
+
+    try:
+        _pcm_queue.put_nowait(block)
+    except queue.Full:
+        try:
+            _pcm_queue.get_nowait()
+        except queue.Empty:
+            pass
+        try:
+            _pcm_queue.put_nowait(block)
+        except queue.Full:
+            pass
+
+
+def shutdown() -> None:
+    """Deactivate the engine.  Called when the Android app stops audio."""
+    global _active
+    _active = False
+    logger.info("Android audio engine shut down")
+
+
+# ---------------------------------------------------------------------------
+# CaptureStream
+# ---------------------------------------------------------------------------
+
+
+class AndroidAudioCaptureStream(AudioCaptureStreamBase):
+    """Reads PCM blocks pushed by Kotlin from the module-level queue."""
+
+    @property
+    def channels(self) -> int:
+        return _channels
+
+    @property
+    def sample_rate(self) -> int:
+        return _sample_rate
+
+    @property
+    def chunk_size(self) -> int:
+        return _chunk_size
+
+    def initialize(self) -> None:
+        if self._initialized:
+            return
+        if not _active:
+            raise RuntimeError(
+                "Android audio engine not configured. "
+                "This engine is only available inside the Android app."
+            )
+        self._initialized = True
+        logger.info("Android audio capture stream initialized")
+
+    def cleanup(self) -> None:
+        self._initialized = False
+        logger.info("Android audio capture stream cleaned up")
+
+    def read_chunk(self) -> np.ndarray | None:
+        try:
+            return _pcm_queue.get(timeout=0.1)  # 1-D float32 interleaved
+        except queue.Empty:
+            return None
+
+
+# ---------------------------------------------------------------------------
+# CaptureEngine
+# ---------------------------------------------------------------------------
+
+
+class AndroidAudioEngine(AudioCaptureEngine):
+    """Android playback-capture audio engine.
+
+    Only available when running inside the LedGrab Android app, which
+    calls :func:`configure` once audio capture is set up.  Exposes a
+    single loopback "device" representing the system audio mix.
+    """
+
+    ENGINE_TYPE = "android_playback"
+    ENGINE_PRIORITY = 100  # highest on a real Android device (demo only wins in demo mode)
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return is_android() and _active
+
+    @classmethod
+    def get_default_config(cls) -> Dict[str, Any]:
+        return {
+            "sample_rate": _sample_rate,
+            "channels": _channels,
+            "chunk_size": _chunk_size,
+        }
+
+    @classmethod
+    def enumerate_devices(cls) -> List[AudioDeviceInfo]:
+        if not cls.is_available():
+            return []
+        return [
+            AudioDeviceInfo(
+                index=0,
+                name="Android playback (system audio)",
+                is_input=True,
+                is_loopback=True,
+                channels=_channels,
+                default_samplerate=float(_sample_rate),
+            )
+        ]
+
+    @classmethod
+    def create_stream(
+        cls,
+        device_index: int,
+        is_loopback: bool,
+        config: Dict[str, Any],
+    ) -> AndroidAudioCaptureStream:
+        merged = {**cls.get_default_config(), **config}
+        return AndroidAudioCaptureStream(device_index, is_loopback, merged)

server/src/ledgrab/core/automations/platform_detector.py

@@ -6,12 +6,14 @@ Non-Windows: graceful degradation (returns empty results).
 
 import asyncio
 import ctypes
+import json
 import os
 import sys
 import threading
 from typing import Set
 
 from ledgrab.utils import get_logger
+from ledgrab.utils.platform import is_android
 
 logger = get_logger(__name__)
 
@@ -21,6 +23,105 @@ if _IS_WINDOWS:
     import ctypes.wintypes
 
 
+# ---------------------------------------------------------------------------
+# Android ForegroundAppBridge interop — lazy + guarded (never at import time)
+# ---------------------------------------------------------------------------
+# Android reports ``sys.platform == "linux"`` so ``_IS_WINDOWS`` is False there;
+# the foreground app is read via the Kotlin ``ForegroundAppBridge`` (UsageStats)
+# instead of Win32 ctypes. These module-level wrappers are the monkeypatch
+# surface used by tests (mirrors ``android_camera_engine``) — patch the module
+# function, not the live ``jclass`` object.
+
+# Emit the "Usage Access not granted" warning only once per process so the ~1s
+# automation poll loop doesn't spam the log while access is missing.
+_warned_no_usage_access = False
+
+
+def _foreground_bridge():
+    """Return the Kotlin ``ForegroundAppBridge`` singleton, or None off-Android.
+
+    The ``from java import jclass`` import only resolves inside the Chaquopy
+    runtime, so it must never run at module import time (this module is imported
+    on desktop CI too). Mirrors ``android_camera_engine._camera_bridge()``.
+    """
+    if not is_android():
+        return None
+    try:
+        from java import jclass  # type: ignore[import-not-found]
+    except ImportError as exc:
+        logger.debug("Chaquopy java interop not available: %s", exc)
+        return None
+    try:
+        return jclass("com.ledgrab.android.ForegroundAppBridge").INSTANCE
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.debug("ForegroundAppBridge singleton unavailable: %s", exc)
+        return None
+
+
+def has_usage_access() -> bool:
+    """Whether Usage Access (PACKAGE_USAGE_STATS) is granted. False off-Android."""
+    bridge = _foreground_bridge()
+    if bridge is None:
+        return False
+    try:
+        return bool(bridge.hasUsageAccess())
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.debug("ForegroundAppBridge.hasUsageAccess failed: %s", exc)
+        return False
+
+
+def get_foreground_package() -> str | None:
+    """Current foreground app package via the Kotlin bridge, or None.
+
+    None off-Android, when the bridge is unavailable, when Usage Access is
+    missing, or when no foreground event is found in the trailing window.
+    Monkeypatched in tests.
+    """
+    bridge = _foreground_bridge()
+    if bridge is None:
+        return None
+    try:
+        pkg = bridge.getForegroundPackage()
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.warning("ForegroundAppBridge.getForegroundPackage failed: %s", exc)
+        return None
+    if pkg is None:
+        return None
+    s = str(pkg).strip()
+    return s or None
+
+
+def list_installed_apps() -> list[dict]:
+    """Launchable apps via the Kotlin bridge: ``[{"package": .., "label": ..}]``.
+
+    Returns ``[]`` off-Android, when the bridge is unavailable, on error, or on
+    invalid JSON. Sorted by label (the bridge sorts; order is preserved here).
+    Monkeypatched in tests.
+    """
+    bridge = _foreground_bridge()
+    if bridge is None:
+        return []
+    try:
+        raw = bridge.listLaunchableApps()  # JSON array string
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.warning("ForegroundAppBridge.listLaunchableApps failed: %s", exc)
+        return []
+    try:
+        parsed = json.loads(str(raw))
+    except (ValueError, TypeError) as exc:  # pragma: no cover - Android-only path
+        logger.warning("ForegroundAppBridge.listLaunchableApps returned invalid JSON: %s", exc)
+        return []
+    apps: list[dict] = []
+    for entry in parsed if isinstance(parsed, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        pkg = entry.get("package")
+        if not pkg:
+            continue
+        apps.append({"package": str(pkg), "label": str(entry.get("label") or pkg)})
+    return apps
+
+
 class PlatformDetector:
     """Detect running processes and the foreground window's process."""
 
@@ -84,6 +185,21 @@ class PlatformDetector:
             ]
             user32.DefWindowProcW.restype = ctypes.c_ssize_t
 
+            # Pin the MSG pointer type so byref(msg) matches the prototype
+            # (Python 3.13 ctypes rejects mismatched POINTER(MSG) caches).
+            LPMSG = ctypes.POINTER(ctypes.wintypes.MSG)
+            user32.GetMessageW.argtypes = [
+                LPMSG,
+                ctypes.wintypes.HWND,
+                ctypes.c_uint,
+                ctypes.c_uint,
+            ]
+            user32.GetMessageW.restype = ctypes.c_int
+            user32.TranslateMessage.argtypes = [LPMSG]
+            user32.TranslateMessage.restype = ctypes.wintypes.BOOL
+            user32.DispatchMessageW.argtypes = [LPMSG]
+            user32.DispatchMessageW.restype = ctypes.c_ssize_t
+
             def wnd_proc(hwnd, msg, wparam, lparam):
                 if msg == WM_POWERBROADCAST and wparam == PBT_POWERSETTINGCHANGE:
                     try:
@@ -200,6 +316,31 @@ class PlatformDetector:
 
     # ---- Process detection ----
 
+    def _get_android_foreground(self) -> tuple:
+        """(package_lowercased, True) for the foreground app on Android.
+
+        Returns ``(None, False)`` when Usage Access is not granted (warned once)
+        or no foreground app is found. ``is_fullscreen`` is reported True because
+        a foreground TV app effectively covers the screen — so an Android rule's
+        ``topmost``/``topmost_fullscreen``/``fullscreen`` match types all behave
+        as "this app is in front". Delegates to the module-level bridge wrappers
+        (the monkeypatch surface used by tests).
+        """
+        global _warned_no_usage_access
+        if not has_usage_access():
+            if not _warned_no_usage_access:
+                logger.warning(
+                    "Android 'Application' automation rules need Usage Access "
+                    "(Settings > Usage access). Foreground-app rules will not match "
+                    "until it is granted."
+                )
+                _warned_no_usage_access = True
+            return (None, False)
+        pkg = get_foreground_package()
+        if not pkg:
+            return (None, False)
+        return (pkg.lower(), True)
+
     def _get_running_processes_sync(self) -> Set[str]:
         """Get set of lowercase process names via Win32 EnumProcesses.
 
@@ -207,7 +348,14 @@ class PlatformDetector:
         which is ~300x faster than WMI (~8ms vs ~3s).  System services
         running under protected accounts are not visible, but all
         user-facing applications are covered.
+
+        On Android there is no process enumeration API (getRunningTasks is
+        restricted); the foreground app is reported as the sole "running" entry
+        as a best-effort so ``match_type="running"`` rules still work.
         """
+        if is_android():
+            pkg, _ = self._get_android_foreground()
+            return {pkg} if pkg else set()
         if not _IS_WINDOWS:
             return set()
 
@@ -261,9 +409,13 @@ class PlatformDetector:
     def _get_topmost_process_sync(self) -> tuple:
         """Get (process_name, is_fullscreen) of the foreground window.
 
-        Returns (None, False) when detection fails.
+        On Android the "foreground window" is the foreground app package (read
+        via the Kotlin ForegroundAppBridge); see ``_get_android_foreground``.
+        Returns (None, False) when detection fails / Usage Access is missing.
         Blocking — call via executor.
         """
+        if is_android():
+            return self._get_android_foreground()
         if not _IS_WINDOWS:
             return (None, False)
 
@@ -354,7 +506,13 @@ class PlatformDetector:
 
         Enumerates all top-level windows and checks each for fullscreen.
         Returns process names (lowercase) whose window covers an entire monitor.
+
+        On Android the foreground app is treated as fullscreen, so it is the
+        sole entry (best-effort, mirrors ``_get_running_processes_sync``).
         """
+        if is_android():
+            pkg, _ = self._get_android_foreground()
+            return {pkg} if pkg else set()
         if not _IS_WINDOWS:
             return set()
 

server/src/ledgrab/core/backup/auto_backup.py

@@ -1,10 +1,12 @@
-"""Auto-backup engine — periodic SQLite snapshot backups."""
+"""Auto-backup engine — periodic SQLite + assets snapshot backups."""
 
 import asyncio
 import os
+import tempfile
+import zipfile
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import List
+from typing import Iterable, List
 
 from ledgrab.storage.database import Database
 from ledgrab.utils import get_logger
@@ -20,19 +22,35 @@ DEFAULT_SETTINGS = {
 # Skip the immediate-on-start backup if a recent backup exists within this window.
 _STARTUP_BACKUP_COOLDOWN = timedelta(minutes=5)
 
-_BACKUP_EXT = ".db"
+# Current write format. ``.db`` is still recognised on read so backups taken
+# by older versions remain listable, restorable, and prunable.
+_BACKUP_EXT = ".zip"
+_RECOGNISED_EXTS: tuple[str, ...] = (".zip", ".db")
+
+# Soft warning threshold — large backups indicate an unbounded assets dir or
+# bloated DB. We don't refuse to write (user data is theirs), but log loudly
+# so the operator can investigate before disk fills up over many intervals.
+_BACKUP_SIZE_WARN_BYTES = 500 * 1024 * 1024  # 500 MB
 
 
 class AutoBackupEngine:
-    """Creates periodic SQLite snapshot backups of the database."""
+    """Creates periodic backups of the database and asset files.
+
+    Each backup is a ZIP archive containing ``ledgrab.db`` plus every file
+    from ``assets_dir`` under ``assets/`` — matching the format produced by
+    the manual ``GET /api/v1/system/backup`` download. The restore endpoint
+    accepts either ``.zip`` or ``.db`` interchangeably.
+    """
 
     def __init__(
         self,
         backup_dir: Path,
         db: Database,
+        assets_dir: Path | None = None,
     ):
         self._backup_dir = Path(backup_dir)
         self._db = db
+        self._assets_dir = Path(assets_dir) if assets_dir else None
         self._task: asyncio.Task | None = None
         self._last_backup_time: datetime | None = None
 
@@ -82,9 +100,14 @@ class AutoBackupEngine:
             self._task.cancel()
             self._task = None
 
+    def _iter_backup_files(self) -> Iterable[Path]:
+        """Yield every backup file (both legacy ``.db`` and current ``.zip``)."""
+        for ext in _RECOGNISED_EXTS:
+            yield from self._backup_dir.glob(f"*{ext}")
+
     def _most_recent_backup_age(self) -> timedelta | None:
         """Return the age of the newest backup file, or None if no backups exist."""
-        files = list(self._backup_dir.glob(f"*{_BACKUP_EXT}"))
+        files = list(self._iter_backup_files())
         if not files:
             return None
         newest = max(files, key=lambda p: p.stat().st_mtime)
@@ -124,15 +147,72 @@ class AutoBackupEngine:
         timestamp = now.strftime("%Y-%m-%dT%H%M%S")
         filename = f"ledgrab-backup-{timestamp}{_BACKUP_EXT}"
         file_path = self._backup_dir / filename
+        # Stage the ZIP at <name>.partial then os.replace into place once it's
+        # fully written. A crash mid-write leaves a .partial file (cleaned up
+        # on the next backup) but never a half-written backup that would fool
+        # ``_most_recent_backup_age`` / ``_prune_old_backups`` into trusting
+        # corrupt data.
+        partial_path = file_path.with_suffix(file_path.suffix + ".partial")
 
-        self._db.backup_to(file_path)
+        # SQLite backup API → temp .db so we get a consistent snapshot
+        # without holding the DB lock for the ZIP write.
+        tmp = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        tmp_path = Path(tmp.name)
+        tmp.close()
+        asset_count = 0
+        try:
+            self._db.backup_to(tmp_path)
+            with zipfile.ZipFile(partial_path, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.write(tmp_path, "ledgrab.db")
+                if self._assets_dir and self._assets_dir.is_dir():
+                    for asset_file in self._assets_dir.iterdir():
+                        # Skip symlinks: ``is_file()`` follows them and we
+                        # don't want to silently slurp a symlink target that
+                        # lives outside the assets dir into every backup.
+                        if asset_file.is_symlink():
+                            continue
+                        if asset_file.is_file():
+                            zf.write(asset_file, f"assets/{asset_file.name}")
+                            asset_count += 1
+            os.replace(partial_path, file_path)
+        except Exception:
+            # Roll back the staged partial so it doesn't accumulate; the
+            # finally block still removes the SQLite temp file. Re-raise so
+            # the caller (``_backup_loop`` / ``trigger_backup``) sees + logs
+            # the failure instead of silently emitting a missing backup.
+            partial_path.unlink(missing_ok=True)
+            raise
+        finally:
+            tmp_path.unlink(missing_ok=True)
 
+        # Best-effort sweep of any older orphan .partial files left by a
+        # crash on a previous run.
+        for stale in self._backup_dir.glob("*.partial"):
+            try:
+                stale.unlink()
+            except OSError:
+                pass
+
+        size_bytes = file_path.stat().st_size
         self._last_backup_time = now
-        logger.info(f"Backup created: {filename}")
+        logger.info(
+            "Backup created: %s (%d asset files, %.1f MB)",
+            filename,
+            asset_count,
+            size_bytes / (1024 * 1024),
+        )
+        if size_bytes > _BACKUP_SIZE_WARN_BYTES:
+            logger.warning(
+                "Backup %s is %.1f MB — exceeds %d MB warning threshold; "
+                "consider pruning the assets directory or lowering max_backups",
+                filename,
+                size_bytes / (1024 * 1024),
+                _BACKUP_SIZE_WARN_BYTES // (1024 * 1024),
+            )
 
     def _prune_old_backups(self) -> None:
         max_backups = self._settings["max_backups"]
-        files = sorted(self._backup_dir.glob(f"*{_BACKUP_EXT}"), key=lambda p: p.stat().st_mtime)
+        files = sorted(self._iter_backup_files(), key=lambda p: p.stat().st_mtime)
         excess = len(files) - max_backups
         if excess > 0:
             for f in files[:excess]:
@@ -179,9 +259,7 @@ class AutoBackupEngine:
 
     def list_backups(self) -> List[dict]:
         backups = []
-        for f in sorted(
+        for f in sorted(self._iter_backup_files(), key=lambda p: p.stat().st_mtime, reverse=True):
-            self._backup_dir.glob(f"*{_BACKUP_EXT}"), key=lambda p: p.stat().st_mtime, reverse=True
-        ):
             stat = f.stat()
             backups.append(
                 {

server/src/ledgrab/core/capture_engines/__init__.py

@@ -86,6 +86,18 @@ try:
 except ImportError:
     _has_mediaprojection = False
 
+# ── Android camera/webcam (Camera2 via Chaquopy bridge) ─────────────
+
+try:
+    from ledgrab.core.capture_engines.android_camera_engine import (
+        AndroidCameraEngine,
+        AndroidCameraCaptureStream,
+    )
+
+    _has_android_camera = True
+except ImportError:
+    _has_android_camera = False
+
 # ── Android root screenrecord (rooted Magisk devices) ───────────────
 
 try:
@@ -120,6 +132,8 @@ if _has_camera:
     EngineRegistry.register(CameraEngine)
 if _has_mediaprojection:
     EngineRegistry.register(MediaProjectionEngine)
+if _has_android_camera:
+    EngineRegistry.register(AndroidCameraEngine)
 if _has_root_screenrecord:
     EngineRegistry.register(RootScreenrecordEngine)
 EngineRegistry.register(DemoCaptureEngine)
@@ -152,5 +166,7 @@ if _has_camera:
     __all__ += ["CameraEngine", "CameraCaptureStream"]
 if _has_mediaprojection:
     __all__ += ["MediaProjectionEngine", "MediaProjectionCaptureStream"]
+if _has_android_camera:
+    __all__ += ["AndroidCameraEngine", "AndroidCameraCaptureStream"]
 if _has_root_screenrecord:
     __all__ += ["RootScreenrecordEngine", "RootScreenrecordCaptureStream"]

server/src/ledgrab/core/capture_engines/android_camera_engine.py

@@ -0,0 +1,430 @@
+"""Android camera (webcam) capture engine.
+
+Receives camera frames pushed from Kotlin (via Chaquopy) through a
+module-level frame queue.  The Kotlin :class:`CameraBridge` opens a
+camera with the Camera2 API, converts each frame to RGB, and calls
+:func:`push_frame` with raw RGB bytes.
+
+The physical camera is opened **on demand** — only while a capture
+stream is active.  :meth:`AndroidCameraCaptureStream.initialize` calls
+:func:`start_camera` (which signals the Kotlin bridge to open the
+camera) and :meth:`cleanup` calls :func:`stop_camera`.  This keeps the
+camera-in-use indicator and battery cost limited to actual use, unlike
+the always-on screen/audio capture.
+
+Mirrors the screen-capture bridge
+(``core/capture_engines/mediaprojection_engine.py``): a module-level
+queue plus push/last-frame fallback/drop-oldest, consumed through the
+standard :class:`CaptureEngine` / :class:`CaptureStream` interface so
+the live-stream and processing pipelines work unchanged.  Cameras are
+exposed as selectable "displays" exactly like the desktop OpenCV
+:class:`CameraEngine`.
+
+This engine is only available when running inside the LedGrab Android
+app (``is_android()``) with at least one camera the Kotlin bridge can
+enumerate.  All Java interop is lazy + guarded so this module imports
+cleanly on desktop CI.
+"""
+
+import json
+import queue
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+from ledgrab.core.capture_engines.base import (
+    CaptureEngine,
+    CaptureStream,
+    DisplayInfo,
+    ScreenCapture,
+)
+from ledgrab.utils import get_logger
+from ledgrab.utils.platform import is_android
+
+logger = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Frame queue — the bridge between Kotlin and Python
+# ---------------------------------------------------------------------------
+
+_frame_queue: "queue.Queue[ScreenCapture]" = queue.Queue(maxsize=2)
+_active = False
+_active_index = 0
+_frames_received = 0
+
+# Single-camera ownership. The Kotlin bridge supports exactly one open camera
+# at a time (it closes any prior camera on a new open), and all streams share
+# the one module-level frame queue. So the engine serializes ownership the way
+# the desktop CameraEngine does with its _camera_lock/_active_cv2_indices: the
+# first stream to initialize() owns the camera; a second stream on the SAME
+# camera attaches (ref-counted); a second stream on a DIFFERENT camera is
+# refused. Only the last owner to clean up actually stops the camera. Without
+# this, two concurrent android_camera sources on different displays would make
+# the second open silently steal the first's frames, and either stream's
+# cleanup would drain the shared queue out from under the other.
+_state_lock = threading.Lock()
+_owner_index: int | None = None  # display_index that currently owns the camera
+_owner_refs = 0  # number of streams attached to the active camera
+# Camera2 delivers frames continuously, but cache the last one so a
+# brief consumer stall still has something to read (mirrors
+# mediaprojection_engine's _last_frame).
+_last_frame: Optional["ScreenCapture"] = None
+
+# Enumeration cache.  is_available() is polled by the engine registry,
+# so the (cheap but non-free) Camera2 enumeration is cached briefly —
+# matching the desktop CameraEngine's 30 s TTL.
+_cam_cache: List[Dict[str, Any]] | None = None
+_cam_cache_time: float = 0.0
+_CAM_CACHE_TTL = 30.0  # seconds
+
+# Resolution presets shown in the UI.  Identical to the desktop
+# CameraEngine set so the data-driven capture-template config UI
+# (keyed by the "resolution" field name) renders the same dropdown.
+# "auto" lets the Kotlin bridge pick a balanced output size.
+_RESOLUTION_CHOICES: List[str] = [
+    "auto",
+    "640x480",
+    "1280x720",
+    "1920x1080",
+    "2560x1440",
+    "3840x2160",
+]
+
+
+def _parse_resolution(value: Any) -> tuple[int, int] | None:
+    """Parse a 'WxH' string into (width, height). None for 'auto'/invalid."""
+    if not isinstance(value, str):
+        return None
+    s = value.strip().lower()
+    if s in ("", "auto"):
+        return None
+    parts = s.replace("×", "x").split("x")
+    if len(parts) != 2:
+        return None
+    try:
+        w, h = int(parts[0]), int(parts[1])
+    except ValueError:
+        return None
+    if w <= 0 or h <= 0:
+        return None
+    return w, h
+
+
+# ---------------------------------------------------------------------------
+# Kotlin CameraBridge interop — lazy + guarded (never at import time)
+# ---------------------------------------------------------------------------
+
+
+def _camera_bridge():
+    """Return the Kotlin ``CameraBridge`` singleton, or None off-Android.
+
+    The ``from java import jclass`` import only resolves inside the
+    Chaquopy runtime, so it must never run at module import time (this
+    module is imported on desktop CI too).  Mirrors
+    ``core/devices/android_ble_transport.py``.
+    """
+    if not is_android():
+        return None
+    try:
+        from java import jclass  # type: ignore[import-not-found]
+    except ImportError as exc:
+        logger.debug("Chaquopy java interop not available: %s", exc)
+        return None
+    try:
+        return jclass("com.ledgrab.android.CameraBridge").INSTANCE
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.debug("CameraBridge singleton unavailable: %s", exc)
+        return None
+
+
+def list_cameras() -> List[Dict[str, Any]]:
+    """Enumerate cameras via the Kotlin bridge.
+
+    Returns a list of ``{"index": int, "name": str, "facing": str}``
+    dicts in stable enumeration order, or ``[]`` off-Android / on error
+    / when the device has no cameras or CAMERA enumeration fails.
+    Monkeypatched in tests to inject a fake list without Android.
+    """
+    bridge = _camera_bridge()
+    if bridge is None:
+        return []
+    try:
+        raw = bridge.listCameras()  # JSON array string
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.warning("CameraBridge.listCameras failed: %s", exc)
+        return []
+    try:
+        parsed = json.loads(str(raw))
+    except (ValueError, TypeError) as exc:  # pragma: no cover
+        logger.warning("CameraBridge.listCameras returned invalid JSON: %s", exc)
+        return []
+    cameras: List[Dict[str, Any]] = []
+    for i, entry in enumerate(parsed if isinstance(parsed, list) else []):
+        if not isinstance(entry, dict):
+            continue
+        cameras.append(
+            {
+                "index": int(entry.get("index", i)),
+                "name": str(entry.get("name") or f"Camera {i}"),
+                "facing": str(entry.get("facing") or "unknown"),
+            }
+        )
+    return cameras
+
+
+def _enumerate_cameras() -> List[Dict[str, Any]]:
+    """Cached camera enumeration (TTL ``_CAM_CACHE_TTL``)."""
+    global _cam_cache, _cam_cache_time
+    now = time.monotonic()
+    if _cam_cache is not None and (now - _cam_cache_time) < _CAM_CACHE_TTL:
+        return _cam_cache
+    _cam_cache = list_cameras()
+    _cam_cache_time = now
+    return _cam_cache
+
+
+def start_camera(index: int, width: int, height: int) -> bool:
+    """Signal the Kotlin bridge to open camera ``index`` (on demand).
+
+    ``width``/``height`` are the requested capture size (0 => let the
+    bridge pick a balanced default).  Returns True if the camera began
+    streaming.  False off-Android, when the bridge is unavailable, or
+    when the open failed (e.g. CAMERA permission denied, camera in use).
+    Monkeypatched in tests.
+    """
+    bridge = _camera_bridge()
+    if bridge is None:
+        return False
+    try:
+        return bool(bridge.startCamera(index, width, height))
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.warning("CameraBridge.startCamera(%d) failed: %s", index, exc)
+        return False
+
+
+def stop_camera(index: int) -> None:
+    """Signal the Kotlin bridge to close the active camera.  No-op off-Android."""
+    bridge = _camera_bridge()
+    if bridge is None:
+        return
+    try:
+        bridge.stopCamera()
+    except Exception as exc:  # pragma: no cover - Android-only path
+        logger.debug("CameraBridge.stopCamera failed: %s", exc)
+
+
+def push_frame(rgb_bytes: bytes, width: int, height: int) -> None:
+    """Push one RGB frame from Kotlin into the capture pipeline.
+
+    Called from ``CameraBridge`` on its capture thread.  The byte buffer
+    is interpreted as tightly-packed RGB (``width * height * 3`` bytes,
+    3 bytes/pixel — NOT RGBA).  The buffer is copied out so Kotlin may
+    reuse its backing array; the oldest queued frame is dropped if the
+    consumer is slow.
+    """
+    global _frames_received, _last_frame
+    expected = width * height * 3
+    if expected <= 0:
+        return
+    arr = np.frombuffer(rgb_bytes, dtype=np.uint8)
+    if arr.size < expected:
+        # Short/malformed buffer — drop rather than reshape-crash.
+        return
+
+    # Copy out of the read-only frombuffer view (and off any reusable
+    # Kotlin buffer) so the queued frame owns its memory.  Mirrors
+    # mediaprojection_engine.push_frame's .copy().
+    rgb = arr[:expected].reshape((height, width, 3)).copy()
+
+    frame = ScreenCapture(
+        image=rgb,
+        width=width,
+        height=height,
+        display_index=_active_index,
+    )
+    _last_frame = frame
+
+    _frames_received += 1
+    if _frames_received == 1 or _frames_received % 100 == 0:
+        logger.info("Android camera: received %d frames", _frames_received)
+
+    # Drop oldest frame if queue is full (non-blocking).
+    try:
+        _frame_queue.put_nowait(frame)
+    except queue.Full:
+        try:
+            _frame_queue.get_nowait()
+        except queue.Empty:
+            pass
+        try:
+            _frame_queue.put_nowait(frame)
+        except queue.Full:
+            pass
+
+
+def shutdown() -> None:
+    """Deactivate the engine.  Called when the Android app stops."""
+    global _active
+    _active = False
+    logger.info("Android camera engine shut down")
+
+
+def _drain_queue() -> None:
+    """Discard any queued frames (stale frames from a prior session)."""
+    global _last_frame
+    while not _frame_queue.empty():
+        try:
+            _frame_queue.get_nowait()
+        except queue.Empty:
+            break
+    _last_frame = None
+
+
+# ---------------------------------------------------------------------------
+# CaptureStream
+# ---------------------------------------------------------------------------
+
+
+class AndroidCameraCaptureStream(CaptureStream):
+    """Reads camera frames pushed by Kotlin from the module-level queue.
+
+    Opening the physical camera is on demand: :meth:`initialize` asks
+    the Kotlin bridge to open the camera bound to ``display_index`` and
+    :meth:`cleanup` asks it to close.
+    """
+
+    def initialize(self) -> None:
+        if self._initialized:
+            return
+        if not is_android():
+            raise RuntimeError(
+                "Android camera engine not available. "
+                "This engine is only usable inside the Android app."
+            )
+
+        parsed = _parse_resolution(self.config.get("resolution", "auto"))
+        target_w, target_h = parsed if parsed is not None else (0, 0)
+
+        global _active, _active_index, _owner_index, _owner_refs
+        with _state_lock:
+            if _owner_index is not None and _owner_index != self.display_index:
+                # Another camera is already streaming — the bridge can only
+                # drive one at a time, so refuse rather than silently stealing
+                # the active camera's frames (mirrors the desktop CameraEngine's
+                # "already in use by another stream").
+                raise RuntimeError(
+                    f"Android camera {_owner_index} is already in use by another "
+                    f"capture; only one camera can stream at a time"
+                )
+            if _owner_index == self.display_index:
+                # Same camera already open — attach to it (ref-counted).
+                _owner_refs += 1
+                self._initialized = True
+                logger.info(
+                    "Android camera capture stream attached (camera=%d, refs=%d)",
+                    self.display_index,
+                    _owner_refs,
+                )
+                return
+
+            # No camera open — open this one. Drain stale frames first so the
+            # first captured frame is actually current.
+            _drain_queue()
+            if not start_camera(self.display_index, target_w, target_h):
+                raise RuntimeError(
+                    f"Failed to open Android camera {self.display_index} "
+                    f"(CAMERA permission denied, camera in use, or unavailable)"
+                )
+            _owner_index = self.display_index
+            _owner_refs = 1
+            _active = True
+            _active_index = self.display_index
+            self._initialized = True
+            logger.info("Android camera capture stream initialized (camera=%d)", self.display_index)
+
+    def capture_frame(self) -> ScreenCapture | None:
+        if not self._initialized:
+            self.initialize()
+        # Prefer a fresh frame; fall back to the last one on a brief stall.
+        try:
+            return _frame_queue.get(timeout=0.1)
+        except queue.Empty:
+            return _last_frame
+
+    def cleanup(self) -> None:
+        if self._initialized:
+            global _active, _owner_index, _owner_refs
+            with _state_lock:
+                _owner_refs -= 1
+                if _owner_refs <= 0:
+                    # Last owner released — actually stop the camera.
+                    stop_camera(self.display_index)
+                    _owner_index = None
+                    _owner_refs = 0
+                    _active = False
+                    _drain_queue()
+            self._initialized = False
+            logger.info("Android camera capture stream cleaned up (camera=%d)", self.display_index)
+        else:
+            self._initialized = False
+
+
+# ---------------------------------------------------------------------------
+# CaptureEngine
+# ---------------------------------------------------------------------------
+
+
+class AndroidCameraEngine(CaptureEngine):
+    """Android camera/webcam capture engine (Camera2 via Kotlin bridge).
+
+    Only available inside the LedGrab Android app with at least one
+    enumerable camera.  Each camera is exposed as a selectable
+    "display", mirroring the desktop OpenCV :class:`CameraEngine`.
+    Selected explicitly via ``engine_type="android_camera"`` in a
+    capture template — never auto-selected (priority 0, below
+    MediaProjection's 100).
+    """
+
+    ENGINE_TYPE = "android_camera"
+    ENGINE_PRIORITY = 0  # never auto-selected over MediaProjection (100); explicit only
+    HAS_OWN_DISPLAYS = True
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return is_android() and len(_enumerate_cameras()) > 0
+
+    @classmethod
+    def get_default_config(cls) -> Dict[str, Any]:
+        return {"resolution": "auto"}
+
+    @classmethod
+    def get_config_choices(cls) -> Dict[str, List[str]]:
+        return {"resolution": list(_RESOLUTION_CHOICES)}
+
+    @classmethod
+    def get_available_displays(cls) -> List[DisplayInfo]:
+        displays: List[DisplayInfo] = []
+        for cam in _enumerate_cameras():
+            idx = cam["index"]
+            displays.append(
+                DisplayInfo(
+                    index=idx,
+                    name=cam["name"],
+                    width=0,
+                    height=0,
+                    x=idx * 500,
+                    y=0,
+                    is_primary=(idx == 0),
+                    refresh_rate=30,
+                )
+            )
+        return displays
+
+    @classmethod
+    def create_stream(
+        cls, display_index: int, config: Dict[str, Any]
+    ) -> AndroidCameraCaptureStream:
+        merged = {**cls.get_default_config(), **config}
+        return AndroidCameraCaptureStream(display_index, merged)

server/src/ledgrab/core/demo_seed.py

@@ -40,6 +40,11 @@ _AS_IDS = {
     "system": "as_demo0001",
 }
 
+_VS_IDS = {
+    "level": "vs_demo0001",
+    "boost": "vs_demo0002",
+}
+
 _TPL_ID = "tpl_demo0001"
 
 _SCENE_ID = "scene_demo0001"
@@ -86,6 +91,7 @@ def seed_demo_data(db: Database) -> None:
     _insert_entities(db, "picture_sources", _build_picture_sources())
     _insert_entities(db, "color_strip_sources", _build_color_strip_sources())
     _insert_entities(db, "audio_sources", _build_audio_sources())
+    _insert_entities(db, "value_sources", _build_value_sources())
     _insert_entities(db, "scene_presets", _build_scene_presets())
 
     logger.info("Demo seed data complete")
@@ -334,6 +340,40 @@ def _build_audio_sources() -> dict:
     }
 
 
+# ── Value Sources ──────────────────────────────────────────────────
+
+
+def _build_value_sources() -> dict:
+    """A static float source plus a template combinator that references it,
+    so demo mode showcases the Jinja template value source out of the box."""
+    return {
+        _VS_IDS["level"]: {
+            "id": _VS_IDS["level"],
+            "name": "Base Level",
+            "source_type": "static",
+            "description": "A constant brightness level (demo input for the template below)",
+            "tags": ["demo"],
+            "value": 0.5,
+            "created_at": _NOW,
+            "updated_at": _NOW,
+        },
+        _VS_IDS["boost"]: {
+            "id": _VS_IDS["boost"],
+            "name": "Boosted Level (template)",
+            "source_type": "template",
+            "return_type": "float",
+            "description": "Jinja combinator: clamps 1.5x the Base Level into [0,1]",
+            "tags": ["demo"],
+            "template": "clamp(level * 1.5)",
+            "inputs": [{"name": "level", "value_source_id": _VS_IDS["level"]}],
+            "default_value": 0.0,
+            "eval_interval": None,
+            "created_at": _NOW,
+            "updated_at": _NOW,
+        },
+    }
+
+
 # ── Scene Presets ──────────────────────────────────────────────────
 
 

server/src/ledgrab/core/processing/composite_stream.py

@@ -8,7 +8,7 @@ import numpy as np
 
 from ledgrab.core.processing.color_strip_stream import ColorStripStream
 from ledgrab.storage.bindable import bfloat
-from ledgrab.utils import get_logger
+from ledgrab.utils import clamp01, get_logger
 from ledgrab.utils.frame_limiter import FrameLimiter
 
 logger = get_logger(__name__)
@@ -176,7 +176,7 @@ class CompositeColorStripStream(ColorStripStream):
                 if i in self._brightness_streams:
                     _vs_id, vs = self._brightness_streams[i]
                     try:
-                        result.append(vs.get_value())
+                        result.append(clamp01(vs.get_value()))
                     except Exception:
                         result.append(None)
                 else:
@@ -660,10 +660,14 @@ class CompositeColorStripStream(ColorStripStream):
                         if layer.get("reverse", False):
                             colors = colors[::-1].copy()
 
-                        # Apply per-layer brightness from value source
+                        # Apply per-layer brightness from value source.
+                        # clamp01 is finite-safe: it rejects nan/inf (which would
+                        # crash the int() cast) and pins out-of-range values into
+                        # [0,1] so the uint16 fixed-point multiply can't wrap on a
+                        # negative. bri == 1.0 correctly skips the scale (no-op).
                         if i in self._brightness_streams:
                             _vs_id, vs = self._brightness_streams[i]
-                            bri = vs.get_value()
+                            bri = clamp01(vs.get_value())
                             if bri < 1.0:
                                 colors = (colors.astype(np.uint16) * int(bri * 256) >> 8).astype(
                                     np.uint8

server/src/ledgrab/core/processing/os_notification_listener.py

@@ -8,6 +8,8 @@ Supported platforms:
 - **Windows**: polls toast notifications via winrt UserNotificationListener
   (falls back to winsdk if winrt packages are not installed)
 - **Linux**: monitors org.freedesktop.Notifications via D-Bus (dbus-next)
+- **Android**: receives notifications pushed from a Kotlin NotificationListenerService
+  via Chaquopy (push-based; see push_notification() and _AndroidBackend)
 """
 
 import asyncio
@@ -17,9 +19,10 @@ import platform
 import threading
 import time
 from pathlib import Path
-from typing import Dict, List, Optional, Set
+from typing import Callable, Dict, List, Optional, Set
 
 from ledgrab.utils import get_logger
+from ledgrab.utils.platform import is_linux
 
 logger = get_logger(__name__)
 
@@ -30,15 +33,71 @@ _HISTORY_MAX = 50
 # Module-level singleton for dependency access
 _instance: Optional["OsNotificationListener"] = None
 
+# Push target for the Android backend — set by _AndroidBackend.start(), read by
+# push_notification(). None when the Android backend isn't running (desktop / server down).
+_android_target: Callable[[str | None], None] | None = None
+
 
 def get_os_notification_listener() -> Optional["OsNotificationListener"]:
     """Return the global OsNotificationListener instance (or None)."""
     return _instance
 
 
+def push_notification(app_name: str | None) -> None:
+    """Receive an Android notification pushed from Kotlin via Chaquopy.
+
+    Called by the LedGrabNotificationListener service through
+    ``Python.getInstance().getModule(...).callAttr("push_notification", label)``.
+    Routes the posting app's display label into the active listener's
+    ``_on_new_notification`` handler. No-op when the Android backend isn't running,
+    so a notification arriving before the server is ready (or on desktop) is safely
+    ignored.
+    """
+    # Snapshot into a local first: stop() may null _android_target concurrently, but an
+    # in-flight push then still completes against the prior callback. Do NOT collapse this
+    # into `if _android_target is not None: _android_target(...)` — that reintroduces a
+    # TOCTOU None-deref race.
+    cb = _android_target
+    if cb is None:
+        return
+    try:
+        cb(app_name)
+    except Exception as exc:  # never let a JNI-side call crash the bound service
+        logger.warning("push_notification callback error: %s", exc)
+
+
 # ── Platform backends ──────────────────────────────────────────────────
 
 
+class _AndroidBackend:
+    """Push-based backend — notifications arrive from Kotlin via push_notification().
+
+    Unlike the Windows/Linux backends (which poll or eavesdrop on a thread), Android
+    notifications are delivered by a Kotlin NotificationListenerService across the
+    Chaquopy JNI boundary into the module-level push_notification() receiver, so
+    start()/stop() simply register/clear the receiver target.
+    """
+
+    def __init__(self, on_notification):
+        self._on_notification = on_notification
+
+    @staticmethod
+    def probe() -> bool:
+        """Return True when running on Android (Chaquopy)."""
+        from ledgrab.utils.platform import is_android
+
+        return is_android()
+
+    def start(self) -> None:
+        global _android_target
+        _android_target = self._on_notification
+        logger.info("OS notification listener: Android backend active")
+
+    def stop(self) -> None:
+        global _android_target
+        _android_target = None
+
+
 def _import_winrt_notifications():
     """Try to import WinRT notification APIs: winrt first, then winsdk fallback.
 
@@ -193,7 +252,9 @@ class _LinuxBackend:
     @staticmethod
     def probe() -> bool:
         """Return True if this backend can run on the current system."""
-        if platform.system() != "Linux":
+        # is_linux() excludes Android, which also reports platform.system() == "Linux"
+        # but has no D-Bus session — defense-in-depth beyond probe ordering.
+        if not is_linux():
             return False
         try:
             import dbus_next  # noqa: F401
@@ -312,8 +373,9 @@ class OsNotificationListener:
         global _instance
         _instance = self
 
-        # Try platform backends in order
+        # Try platform backends in order (Android first — it reports platform.system()
-        for backend_cls in (_WindowsBackend, _LinuxBackend):
+        # == "Linux", so probing it ahead of _LinuxBackend is the robust ordering).
+        for backend_cls in (_AndroidBackend, _WindowsBackend, _LinuxBackend):
             if backend_cls.probe():
                 self._backend = backend_cls(on_notification=self._on_new_notification)
                 self._backend.start()

server/src/ledgrab/core/processing/power_limit.py

@@ -0,0 +1,58 @@
+"""Automatic brightness limiting (ABL) — keep a strip within a PSU current budget.
+
+Estimates the current an addressable LED strip would draw for a frame of
+already-brightness-scaled RGB bytes and, if it exceeds the configured budget,
+returns a uniform scale factor to bring it back under budget. This prevents the
+classic under-spec'd-PSU failure mode: a full-white scene browning out the rail
+(voltage sag -> red/orange shift, flicker, controller resets) — which reads to a
+new user as "this software is broken".
+
+Model: one addressable LED at full white ``(255, 255, 255)`` draws
+``milliamps_per_led`` mA, and current scales linearly with the sum of channel
+values, so a frame's draw is::
+
+    estimated_ma = sum(channel_bytes) * milliamps_per_led / (255 * 3)
+
+(``255 * 3 = 765`` channel-units == one LED at full white.) Standby/idle current
+is intentionally ignored: the limiter only needs to catch the high-draw frames
+that cause brownouts, and the default 55 mA/LED already carries real-world
+headroom. The same convention as WLED's "maximum current" setting.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# Channel units in one LED at full white (R + G + B = 255 * 3).
+_FULL_WHITE_UNITS = 765.0
+
+# Typical full-white draw of a single WS2812/SK6812-class LED, in mA.
+DEFAULT_MILLIAMPS_PER_LED = 55
+
+
+def estimate_current_ma(colors: np.ndarray, milliamps_per_led: int) -> float:
+    """Estimate strip draw (mA) for already-brightness-scaled RGB bytes.
+
+    ``colors`` is an ``(N, 3)`` uint8 array of the values actually sent to the
+    strip. Full white over ``N`` LEDs returns ``N * milliamps_per_led``.
+    """
+    if milliamps_per_led <= 0 or colors.size == 0:
+        return 0.0
+    channel_sum = float(int(colors.sum()))
+    return channel_sum * milliamps_per_led / _FULL_WHITE_UNITS
+
+
+def power_limit_scale(colors: np.ndarray, max_milliamps: int, milliamps_per_led: int) -> float:
+    """Return a scale in ``(0, 1]`` that keeps estimated draw within budget.
+
+    Returns ``1.0`` when limiting is disabled (``max_milliamps <= 0``) or the
+    frame is already within budget. Because current is linear in the channel
+    values, scaling every pixel by ``max_milliamps / estimated`` lands the frame
+    exactly on the budget.
+    """
+    if max_milliamps <= 0 or milliamps_per_led <= 0:
+        return 1.0
+    estimated = estimate_current_ma(colors, milliamps_per_led)
+    if estimated <= max_milliamps:
+        return 1.0
+    return max_milliamps / estimated

server/src/ledgrab/core/processing/processor_manager.py

@@ -407,6 +407,8 @@ class ProcessorManager(AutoRestartMixin, DeviceHealthMixin, DeviceTestModeMixin)
         min_brightness_threshold: int = 0,
         adaptive_fps: bool = False,
         protocol: str = "ddp",
+        max_milliamps: int = 0,
+        milliamps_per_led: int = 55,
     ):
         """Register a WLED target processor."""
         if target_id in self._processors:
@@ -425,6 +427,8 @@ class ProcessorManager(AutoRestartMixin, DeviceHealthMixin, DeviceTestModeMixin)
             min_brightness_threshold=min_brightness_threshold,
             adaptive_fps=adaptive_fps,
             protocol=protocol,
+            max_milliamps=max_milliamps,
+            milliamps_per_led=milliamps_per_led,
             ctx=self._build_context(),
         )
         self._processors[target_id] = proc

server/src/ledgrab/core/processing/value_kinds.py

@@ -193,6 +193,7 @@ def _build_ha_entity(source, d: ValueStreamDeps):
         min_ha_value=source.min_ha_value,
         max_ha_value=source.max_ha_value,
         smoothing=source.smoothing,
+        normalize=source.normalize,
         ha_manager=d.ha_manager,
     )
 
@@ -232,6 +233,7 @@ def _build_system_metrics(source, _d: ValueStreamDeps):
         sensor_label=source.sensor_label,
         poll_interval=source.poll_interval,
         smoothing=source.smoothing,
+        normalize=source.normalize,
     )
 
 
@@ -249,6 +251,7 @@ def _build_game_event(source, d: ValueStreamDeps):
         smoothing=source.smoothing,
         default_value=source.default_value,
         timeout=source.timeout,
+        normalize=source.normalize,
         event_bus=d.event_bus,
     )
 
@@ -263,10 +266,25 @@ def _build_http(source, d: ValueStreamDeps):
         min_value=source.min_value,
         max_value=source.max_value,
         smoothing=source.smoothing,
+        normalize=source.normalize,
         http_endpoint_store=d.http_endpoint_store,
     )
 
 
+def _build_template(source, d: ValueStreamDeps):
+    # References other value sources via d.value_stream_manager (recursively
+    # acquired in start()), exactly like _build_gradient_map.
+    from ledgrab.core.processing.value_stream import TemplateValueStream
+
+    return TemplateValueStream(
+        template=source.template,
+        inputs=source.inputs,
+        default_value=source.default_value,
+        eval_interval=source.eval_interval,
+        value_stream_manager=d.value_stream_manager,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Registry
 # ---------------------------------------------------------------------------
@@ -290,6 +308,7 @@ STREAM_BUILDERS: dict[str, StreamBuilder] = {
     "system_metrics": _build_system_metrics,
     "game_event": _build_game_event,
     "http": _build_http,
+    "template": _build_template,
 }
 
 

server/src/ledgrab/core/processing/value_stream.py

@@ -33,7 +33,12 @@ import numpy as np
 
 from ledgrab.core.processing import metric_readers as _metric_readers
 from ledgrab.storage.base_store import EntityNotFoundError
-from ledgrab.utils import get_logger
+from ledgrab.utils import clamp01, get_logger
+from ledgrab.utils.template_expr import (
+    TemplateValidationError,
+    compile_template,
+    finalize_result,
+)
 
 # Compiled once — used by ``_extract_simple_path`` on every poll.
 _NAME_HEAD_RE = re.compile(r"^([^\[]*)")
@@ -53,6 +58,12 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+# Runtime cap on recursive value-stream acquisition (referencing sources like
+# template / gradient_map re-enter acquire() from start()). Higher than the
+# storage-level MAX_VALUE_SOURCE_DEPTH (8) so legitimate chains never trip it;
+# it only fires on a cycle that bypassed storage validation.
+_MAX_ACQUIRE_DEPTH = 12
+
 
 # ---------------------------------------------------------------------------
 # Base class
@@ -904,6 +915,7 @@ class HAEntityValueStream(ValueStream):
         min_ha_value: float = 0.0,
         max_ha_value: float = 100.0,
         smoothing: float = 0.0,
+        normalize: bool = True,
         ha_manager: Any | None = None,
     ):
         self._ha_source_id = ha_source_id
@@ -912,6 +924,7 @@ class HAEntityValueStream(ValueStream):
         self._min_ha = min_ha_value
         self._max_ha = max_ha_value
         self._smoothing = smoothing
+        self._normalize_enabled = normalize
         self._ha_manager = ha_manager
         self._prev_value: float | None = None
         self._raw_value: float | None = None
@@ -976,16 +989,23 @@ class HAEntityValueStream(ValueStream):
 
         self._raw_value = raw
 
-        # Normalize to [0, 1]
+        if self._normalize_enabled:
-        ha_range = self._max_ha - self._min_ha
+            # Normalize to [0, 1] via the configured min/max range.
-        if abs(ha_range) < 1e-9:
+            ha_range = self._max_ha - self._min_ha
-            normalized = 0.5
+            if abs(ha_range) < 1e-9:
+                normalized = 0.5
+            else:
+                normalized = (raw - self._min_ha) / ha_range
+            normalized = max(0.0, min(1.0, normalized))
         else:
-            normalized = (raw - self._min_ha) / ha_range
+            # Skip the rescale: treat the raw reading as already a 0–1 fraction
+            # (finite-safe clamp). The un-clamped magnitude stays on
+            # get_raw_value(); get_value() never leaves [0, 1] either way.
+            normalized = clamp01(raw)
 
-        normalized = max(0.0, min(1.0, normalized))
+        # EMA smoothing — both branches produce a [0, 1] value, so _prev_value
-
+        # is always normalized and flipping ``normalize`` live never blends a
-        # EMA smoothing
+        # raw magnitude against a fraction.
         if self._smoothing > 0.0 and self._prev_value is not None:
             normalized = self._smoothing * self._prev_value + (1.0 - self._smoothing) * normalized
 
@@ -1009,6 +1029,7 @@ class HAEntityValueStream(ValueStream):
         self._min_ha = source.min_ha_value
         self._max_ha = source.max_ha_value
         self._smoothing = source.smoothing
+        self._normalize_enabled = source.normalize
 
         # If HA source changed, swap runtime
         if source.ha_source_id != old_ha_source and self._ha_manager:
@@ -1052,6 +1073,7 @@ class HTTPValueStream(ValueStream):
         min_value: float,
         max_value: float,
         smoothing: float,
+        normalize: bool = True,
         http_endpoint_store: "HTTPEndpointStore" | None = None,
     ) -> None:
         self._endpoint_id = endpoint_id
@@ -1060,6 +1082,7 @@ class HTTPValueStream(ValueStream):
         self._min_value = min_value
         self._max_value = max_value
         self._smoothing = smoothing
+        self._normalize_enabled = normalize
         self._http_endpoint_store = http_endpoint_store
         self._task: asyncio.Task | None = None
         self._raw_value: Any = None
@@ -1099,12 +1122,19 @@ class HTTPValueStream(ValueStream):
         except (TypeError, ValueError):
             return self._prev_normalized if self._prev_normalized is not None else 0.0
 
-        rng = self._max_value - self._min_value
+        if self._normalize_enabled:
-        if abs(rng) < 1e-9:
+            rng = self._max_value - self._min_value
-            normalized = 0.5
+            if abs(rng) < 1e-9:
+                normalized = 0.5
+            else:
+                normalized = (numeric - self._min_value) / rng
+            normalized = max(0.0, min(1.0, normalized))
         else:
-            normalized = (numeric - self._min_value) / rng
+            # Skip the rescale: treat the extracted number as already a 0–1
-        normalized = max(0.0, min(1.0, normalized))
+            # fraction (finite-safe clamp). The verbatim extracted value (which
+            # may be non-numeric) stays on get_raw_value(); get_value() is always
+            # a float in [0, 1].
+            normalized = clamp01(numeric)
 
         if self._smoothing > 0.0 and self._prev_normalized is not None:
             normalized = (
@@ -1128,6 +1158,7 @@ class HTTPValueStream(ValueStream):
         self._min_value = source.min_value
         self._max_value = source.max_value
         self._smoothing = source.smoothing
+        self._normalize_enabled = source.normalize
 
     async def _poll_loop(self) -> None:
         from ledgrab.utils.safe_source import safe_request_bounded
@@ -1365,6 +1396,168 @@ class GradientMapValueStream(ValueStream):
                     self._inner_stream = None
 
 
+# ---------------------------------------------------------------------------
+# Template (Jinja expression combinator)
+# ---------------------------------------------------------------------------
+
+
+class TemplateValueStream(ValueStream):
+    """Evaluates a hardened sandboxed-Jinja expression over the live values of
+    other value sources (the system's float combinator).
+
+    Acquires each referenced input stream from the manager on ``start()`` and
+    releases it on ``stop()`` — the same ref-counted protocol as
+    :class:`GradientMapValueStream`, but over a *set* of inputs. Acquisition is
+    tracked per unique ``value_source_id`` so two variables bound to the same
+    source share one ref. ``get_value()`` builds a primitives-only context
+    (each input's normalized ``get_value()`` plus a float-only ``raw`` dict),
+    evaluates the compiled expression, then coerces / NaN-guards / clamps the
+    result. Any error — or an uncompilable template — falls back to
+    ``default_value``. An optional ``eval_interval`` caches the last result to
+    bound steady-state evaluation cost.
+    """
+
+    def __init__(
+        self,
+        template: str,
+        inputs: List[dict],
+        default_value: float = 0.0,
+        eval_interval: float | None = None,
+        value_stream_manager: "ValueStreamManager" | None = None,
+    ):
+        self._template = template
+        self._inputs = [dict(i) for i in (inputs or [])]
+        self._default = max(0.0, min(1.0, float(default_value)))
+        self._eval_interval = float(eval_interval) if eval_interval else 0.0
+        self._vsm = value_stream_manager
+        self._streams_by_id: Dict[str, ValueStream] = {}  # value_source_id -> stream
+        self._expr = self._compile(template)
+        self._last_value: float = self._default
+        self._last_eval: float = 0.0
+        self._has_value = False
+        self._error_logged = False
+
+    @staticmethod
+    def _compile(template: str):
+        """Compile once; return ``None`` (→ always default) on invalid template.
+
+        Creation should already have rejected invalid templates via the factory;
+        this is defense in depth so a bad row never crashes the engine.
+        """
+        try:
+            return compile_template(template)
+        except TemplateValidationError as e:
+            logger.warning("TemplateValueStream: invalid template, using default (%s)", e)
+            return None
+
+    @staticmethod
+    def _unique_ids(inputs: List[dict]) -> set:
+        return {i["value_source_id"] for i in inputs if i.get("value_source_id")}
+
+    def start(self) -> None:
+        if not self._vsm:
+            return
+        for vs_id in self._unique_ids(self._inputs):
+            try:
+                self._streams_by_id[vs_id] = self._vsm.acquire(vs_id)
+            except Exception as e:
+                logger.warning("TemplateValueStream: failed to acquire input %s: %s", vs_id, e)
+
+    def stop(self) -> None:
+        if self._vsm:
+            for vs_id in list(self._streams_by_id):
+                try:
+                    self._vsm.release(vs_id)
+                except Exception as e:
+                    logger.debug("TemplateValueStream: release %s failed: %s", vs_id, e)
+        self._streams_by_id.clear()
+        self._has_value = False
+
+    def get_value(self) -> float:
+        if self._expr is None:
+            return self._default
+
+        if (
+            self._eval_interval > 0.0
+            and self._has_value
+            and (time.monotonic() - self._last_eval) < self._eval_interval
+        ):
+            return self._last_value
+
+        try:
+            ctx: Dict[str, Any] = {}
+            raw: Dict[str, float] = {}
+            for inp in self._inputs:
+                name = inp.get("name")
+                vs_id = inp.get("value_source_id")
+                if not name or not vs_id:
+                    continue
+                stream = self._streams_by_id.get(vs_id)
+                if stream is None:
+                    continue
+                ctx[name] = float(stream.get_value())
+                getter = getattr(stream, "get_raw_value", None)
+                if getter is not None:
+                    rv = getter()
+                    if rv is not None:
+                        try:
+                            raw[name] = float(rv)
+                        except (TypeError, ValueError):
+                            # Non-numeric raw values never cross into the sandbox.
+                            pass
+            ctx["raw"] = raw
+            # Globals (min/max/abs/round/clamp) resolve from SANDBOX_ENV.globals.
+            value = finalize_result(self._expr(**ctx), self._default)
+        except Exception as e:
+            if not self._error_logged:
+                logger.warning("TemplateValueStream eval error (using default): %s", e)
+                self._error_logged = True
+            value = self._default
+
+        self._last_value = value
+        self._last_eval = time.monotonic()
+        self._has_value = True
+        return value
+
+    def update_source(self, source: "ValueSource") -> None:
+        from ledgrab.storage.value_source import TemplateValueSource
+
+        if not isinstance(source, TemplateValueSource):
+            return
+
+        if source.template != self._template:
+            self._template = source.template
+            self._expr = self._compile(source.template)
+            self._error_logged = False
+
+        self._default = max(0.0, min(1.0, float(source.default_value)))
+        self._eval_interval = float(source.eval_interval) if source.eval_interval else 0.0
+
+        new_inputs = [dict(i) for i in (source.inputs or [])]
+        old_ids = set(self._streams_by_id)
+        new_ids = self._unique_ids(new_inputs)
+
+        if self._vsm:
+            # Release-before-acquire (mirrors GradientMapValueStream); safe under
+            # ref-counting. Unchanged ids keep their existing stream untouched.
+            for vs_id in old_ids - new_ids:
+                try:
+                    self._vsm.release(vs_id)
+                except Exception as e:
+                    logger.debug("TemplateValueStream: release %s failed: %s", vs_id, e)
+                self._streams_by_id.pop(vs_id, None)
+            for vs_id in new_ids - old_ids:
+                try:
+                    self._streams_by_id[vs_id] = self._vsm.acquire(vs_id)
+                except Exception as e:
+                    logger.warning("TemplateValueStream: acquire %s failed: %s", vs_id, e)
+
+        # Rebuild inputs (re-keys variable names on rename even when id unchanged,
+        # since get_value() maps name -> stream via value_source_id each tick).
+        self._inputs = new_inputs
+        self._has_value = False
+
+
 # ---------------------------------------------------------------------------
 # CSS Extract
 # ---------------------------------------------------------------------------
@@ -1501,6 +1694,7 @@ class SystemMetricsValueStream(ValueStream):
         sensor_label: str = "",
         poll_interval: float = 1.0,
         smoothing: float = 0.0,
+        normalize: bool = True,
     ):
         self._metric = metric
         self._min_val = min_value
@@ -1510,6 +1704,7 @@ class SystemMetricsValueStream(ValueStream):
         self._sensor_label = sensor_label
         self._poll_interval = max(0.1, poll_interval)
         self._smoothing = smoothing
+        self._normalize_enabled = normalize
         self._prev_value: float | None = None
         self._raw_value: float | None = None
         self._last_poll: float = 0.0
@@ -1548,10 +1743,16 @@ class SystemMetricsValueStream(ValueStream):
         raw = self._read_metric()
         self._raw_value = raw
 
-        # Normalize
+        if self._normalize_enabled:
-        normalized = self._normalize(raw)
+            normalized = self._normalize(raw)
+        else:
+            # Skip the rescale: treat the raw reading as already a 0–1 fraction
+            # (finite-safe clamp). The un-clamped reading stays on
+            # get_raw_value(); get_value() never leaves [0, 1].
+            normalized = clamp01(raw)
 
-        # EMA smoothing
+        # EMA smoothing — both branches output [0, 1], so _prev_value is always
+        # normalized and a live ``normalize`` flip never blends raw vs fraction.
         if self._smoothing > 0.0 and self._prev_value is not None:
             normalized = self._smoothing * self._prev_value + (1.0 - self._smoothing) * normalized
 
@@ -1599,6 +1800,7 @@ class SystemMetricsValueStream(ValueStream):
         self._sensor_label = source.sensor_label
         self._poll_interval = max(0.1, source.poll_interval)
         self._smoothing = source.smoothing
+        self._normalize_enabled = source.normalize
 
 
 # ---------------------------------------------------------------------------
@@ -1644,6 +1846,10 @@ class ValueStreamManager:
         self._http_endpoint_store = http_endpoint_store
         self._streams: Dict[str, ValueStream] = {}  # vs_id → stream
         self._ref_counts: Dict[str, int] = {}  # vs_id → ref count
+        # Recursion-depth backstop for referencing sources (template / gradient
+        # map). A cycle that slipped past storage validation (e.g. a hand-edited
+        # DB or restored backup) would otherwise overflow the stack at acquire().
+        self._acquire_depth = 0
         # Tracks which clock_id (if any) was acquired for each stream so we
         # can release/swap it without re-querying the store at teardown time.
         self._stream_clock_ids: Dict[str, str] = {}  # vs_id → clock_id
@@ -1659,9 +1865,29 @@ class ValueStreamManager:
             logger.info(f"Shared value stream {vs_id} (refs={self._ref_counts[vs_id]})")
             return self._streams[vs_id]
 
+        if self._acquire_depth >= _MAX_ACQUIRE_DEPTH:
+            logger.warning(
+                "Value source acquire depth limit (%d) reached at %s; returning "
+                "static fallback (possible reference cycle)",
+                _MAX_ACQUIRE_DEPTH,
+                vs_id,
+            )
+            # The intermediate referencing streams built while descending a
+            # cyclic chain are not stop()'d here — but this only triggers on a
+            # stored cycle that storage validation already rejects (e.g. a
+            # hand-edited DB / corrupt restore), so those transient objects are
+            # simply garbage-collected. Normal graphs never reach this depth.
+            return StaticValueStream(0.5)
+
         source = self._value_source_store.get_source(vs_id)
-        stream = self._create_stream(source, vs_id)
+        # Increment around create+start: a referencing stream (template /
-        stream.start()
+        # gradient_map) re-enters acquire() from its own start().
+        self._acquire_depth += 1
+        try:
+            stream = self._create_stream(source, vs_id)
+            stream.start()
+        finally:
+            self._acquire_depth -= 1
         self._streams[vs_id] = stream
         self._ref_counts[vs_id] = 1
         logger.info(f"Acquired value stream {vs_id} (type={source.source_type})")

server/src/ledgrab/core/processing/wled_target_processor.py

@@ -17,6 +17,7 @@ from ledgrab.core.devices.led_client import (
     get_device_capabilities,
 )
 from ledgrab.core.capture.screen_capture import get_available_displays
+from ledgrab.core.processing.power_limit import DEFAULT_MILLIAMPS_PER_LED, power_limit_scale
 from ledgrab.core.processing.target_processor import (
     ProcessingMetrics,
     TargetContext,
@@ -62,6 +63,8 @@ class WledTargetProcessor(TargetProcessor):
         min_brightness_threshold: int = 0,
         adaptive_fps: bool = False,
         protocol: str = "ddp",
+        max_milliamps: int = 0,
+        milliamps_per_led: int = 55,
         ctx: TargetContext = None,
     ):
         from ledgrab.storage.bindable import BindableFloat, bfloat
@@ -81,6 +84,13 @@ class WledTargetProcessor(TargetProcessor):
         self._min_brightness_threshold = int(bfloat(min_brightness_threshold, 0.0))
         self._adaptive_fps = adaptive_fps
         self._protocol = protocol
+        # Automatic brightness limiting (ABL). 0 mA budget = disabled.
+        self._max_milliamps = max(0, int(max_milliamps or 0))
+        self._milliamps_per_led = max(1, int(milliamps_per_led or DEFAULT_MILLIAMPS_PER_LED))
+        # Reusable scratch for in-place power scaling (allocated on first use).
+        self._power_u16: np.ndarray | None = None
+        self._power_out: np.ndarray | None = None
+        self._power_n = 0
 
         # Adaptive FPS / liveness probe runtime state
         self._effective_fps: int = self._target_fps
@@ -313,6 +323,12 @@ class WledTargetProcessor(TargetProcessor):
                 self._adaptive_fps = settings["adaptive_fps"]
                 if not self._adaptive_fps:
                     self._effective_fps = self._target_fps
+            if "max_milliamps" in settings:
+                self._max_milliamps = max(0, int(settings["max_milliamps"] or 0))
+            if "milliamps_per_led" in settings:
+                self._milliamps_per_led = max(
+                    1, int(settings["milliamps_per_led"] or DEFAULT_MILLIAMPS_PER_LED)
+                )
         logger.info(f"Updated settings for target {self._target_id}")
 
     def update_device(self, device_id: str) -> None:
@@ -787,8 +803,33 @@ class WledTargetProcessor(TargetProcessor):
         np.copyto(out, blend, casting="unsafe")  # float32 → uint8
         return out
 
+    def _apply_power_limit(self, colors: np.ndarray) -> np.ndarray:
+        """Scale ``colors`` down to stay within the PSU current budget (ABL).
+
+        Returns ``colors`` unchanged when limiting is disabled or the frame is
+        already within budget; otherwise returns a scaled copy in a reusable
+        scratch buffer (the input is never mutated — it may be a shared frame).
+        """
+        if self._max_milliamps <= 0:
+            return colors
+        scale = power_limit_scale(colors, self._max_milliamps, self._milliamps_per_led)
+        if scale >= 1.0:
+            return colors
+        factor = int(scale * 256)  # 0..255 fixed-point multiplier
+        n = len(colors)
+        if self._power_u16 is None or self._power_n != n:
+            self._power_n = n
+            self._power_u16 = np.empty((n, 3), dtype=np.uint16)
+            self._power_out = np.empty((n, 3), dtype=np.uint8)
+        np.copyto(self._power_u16, colors, casting="unsafe")
+        self._power_u16 *= factor
+        self._power_u16 >>= 8
+        np.copyto(self._power_out, self._power_u16, casting="unsafe")
+        return self._power_out
+
     async def _send_to_device(self, send_colors: np.ndarray) -> float:
         """Send colors to LED device and return send time in ms."""
+        send_colors = self._apply_power_limit(send_colors)
         t_start = time.perf_counter()
         if self._led_client.supports_fast_send:
             self._led_client.send_pixels_fast(send_colors)

server/src/ledgrab/core/value_sources/game_event_value_source.py

@@ -15,7 +15,7 @@ import time
 from typing import TYPE_CHECKING
 
 from ledgrab.core.processing.value_stream import ValueStream
-from ledgrab.utils import get_logger
+from ledgrab.utils import clamp01, get_logger
 
 if TYPE_CHECKING:
     from ledgrab.core.game_integration.event_bus import GameEventBus
@@ -41,6 +41,7 @@ class GameEventValueStream(ValueStream):
         smoothing: float = 0.0,
         default_value: float = 0.5,
         timeout: float = 5.0,
+        normalize: bool = True,
         event_bus: "GameEventBus" | None = None,
     ) -> None:
         self._event_type = event_type
@@ -49,10 +50,15 @@ class GameEventValueStream(ValueStream):
         self._smoothing = max(0.0, min(1.0, smoothing))
         self._default_value = max(0.0, min(1.0, default_value))
         self._timeout = max(0.0, timeout)
+        # When False, skip the min/max rescale: the [0,1] output clamps the raw
+        # value as-is. get_value() stays in [0,1] either way; the un-clamped
+        # value is exposed via get_raw_value() for templates/automations.
+        self._normalize_enabled = normalize
         self._event_bus = event_bus
 
         self._lock = threading.Lock()
         self._current_value: float = self._default_value
+        self._current_raw: float | None = None
         self._last_event_time: float | None = None
         self._subscription_id: str | None = None
         self._has_received_event: bool = False
@@ -82,11 +88,18 @@ class GameEventValueStream(ValueStream):
             self._subscription_id = None
         with self._lock:
             self._current_value = self._default_value
+            self._current_raw = None
             self._last_event_time = None
             self._has_received_event = False
 
     def get_value(self) -> float:
-        """Return current normalized value (0.0-1.0), or default if timed out."""
+        """Return current value in [0,1], or default_value if timed out.
+
+        Always in [0,1]: ``_current_value`` holds the smoothed output computed
+        at event time under the active ``normalize`` mode (rescaled, or the raw
+        value clamped into [0,1]). ``default_value`` is itself in [0,1], so the
+        timeout fallback is valid in both modes.
+        """
         with self._lock:
             if not self._has_received_event:
                 return self._default_value
@@ -98,6 +111,15 @@ class GameEventValueStream(ValueStream):
 
             return self._current_value
 
+    def get_raw_value(self) -> float | None:
+        """Return the last raw game value before normalization.
+
+        ``None`` until the first event arrives (mirrors HA/HTTP/SystemMetrics).
+        Exposes the un-clamped magnitude to template ``raw[]`` and automations.
+        """
+        with self._lock:
+            return self._current_raw
+
     def get_color(self) -> tuple:
         """Game event value source only provides scalars, not colors."""
         raise NotImplementedError("GameEventValueStream does not produce colors")
@@ -115,6 +137,7 @@ class GameEventValueStream(ValueStream):
             self._smoothing = max(0.0, min(1.0, source.smoothing))
             self._default_value = max(0.0, min(1.0, source.default_value))
             self._timeout = max(0.0, source.timeout)
+            self._normalize_enabled = source.normalize
 
     def _on_event(self, event: "GameEvent") -> None:
         """EventBus callback — normalize and apply smoothing.
@@ -122,14 +145,17 @@ class GameEventValueStream(ValueStream):
         Called from the publisher's thread; must be thread-safe.
         """
         raw_value = event.value
-        normalized = self._normalize(raw_value)
+        # Output is always in [0,1]: rescale via min/max, or (normalize off)
+        # clamp the raw value as-is. The un-clamped raw is kept for get_raw_value().
+        out = self._normalize(raw_value) if self._normalize_enabled else clamp01(raw_value)
 
         with self._lock:
+            self._current_raw = raw_value
             if self._smoothing > 0.0 and self._has_received_event:
                 alpha = 1.0 - self._smoothing
-                normalized = alpha * normalized + self._smoothing * self._current_value
+                out = alpha * out + self._smoothing * self._current_value
 
-            self._current_value = normalized
+            self._current_value = out
             self._last_event_time = time.monotonic()
             self._has_received_event = True
 

server/src/ledgrab/demo.py

@@ -15,6 +15,7 @@ def main():
 
     import uvicorn
     from ledgrab.config import get_config
+    from ledgrab.shutdown_state import GRACEFUL_SHUTDOWN_TIMEOUT
 
     config = get_config()
     uvicorn.run(
@@ -22,7 +23,14 @@ def main():
         host=config.server.host,
         port=config.server.port,
         log_level=config.server.log_level.lower(),
+        # Access logging is handled by the _access_log middleware (with token
+        # attribution); disable uvicorn's to avoid duplicate lines.
+        access_log=False,
         reload=False,
+        # Bound the graceful-shutdown wait so Ctrl+C with the UI open still
+        # runs the lifespan shutdown instead of hanging on a lingering events
+        # WebSocket — see shutdown_state.
+        timeout_graceful_shutdown=GRACEFUL_SHUTDOWN_TIMEOUT,
     )
 
 

server/src/ledgrab/main.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import sys
+import time
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Awaitable
@@ -74,7 +75,7 @@ config = get_config()
 
 # The shutdown-complete signal is owned by a leaf module so ``__main__``
 # can import it without dragging in this module's heavy global state.
-from ledgrab.shutdown_state import shutdown_complete  # noqa: E402
+from ledgrab.shutdown_state import GRACEFUL_SHUTDOWN_TIMEOUT, shutdown_complete  # noqa: E402
 
 
 def _migrate_legacy_data_location() -> None:
@@ -283,6 +284,7 @@ async def lifespan(app: FastAPI):
     auto_backup_engine = AutoBackupEngine(
         backup_dir=_data_dir / "backups",
         db=db,
+        assets_dir=Path(config.assets.assets_dir),
     )
 
     # Create update service (checks for new releases)
@@ -576,6 +578,33 @@ async def _security_headers(request: Request, call_next):
     return response
 
 
+# Middleware: structured access log enriched with the authenticated token's
+# friendly label (the key name from auth.api_keys), so requests can be
+# attributed to a specific client (e.g. "homeassistant" vs "android"). The
+# label is set onto request.state by verify_api_key; endpoints without auth
+# (or failed auth) log "unauthenticated". Only the label is logged — never the
+# token secret. Registered last so it runs outermost: it measures total
+# handling time and always records the final status, even on error.
+@app.middleware("http")
+async def _access_log(request: Request, call_next):
+    start = time.perf_counter()
+    status_code = 500
+    try:
+        response = await call_next(request)
+        status_code = response.status_code
+        return response
+    finally:
+        logger.info(
+            "http_request",
+            method=request.method,
+            path=request.url.path,
+            status=status_code,
+            token=getattr(request.state, "auth_label", None) or "unauthenticated",
+            client=request.client.host if request.client else None,
+            duration_ms=round((time.perf_counter() - start) * 1000, 1),
+        )
+
+
 # ── Auth-gated OpenAPI surface ────────────────────────────────────────────
 # Re-add the docs endpoints we disabled above, now protected by the same
 # Bearer auth as the rest of the API. When auth is unconfigured, loopback
@@ -644,5 +673,13 @@ if __name__ == "__main__":
         host=config.server.host,
         port=config.server.port,
         log_level=config.server.log_level.lower(),
+        # Our _access_log middleware emits a richer structured line (incl. the
+        # authenticated token label), so suppress uvicorn's default access log
+        # to avoid two lines per request.
+        access_log=False,
         reload=False,  # Disabled due to watchfiles infinite reload loop
+        # Bound the graceful-shutdown wait so Ctrl+C with the UI open still
+        # runs the lifespan shutdown (stop targets + DB checkpoint) instead of
+        # hanging on a lingering events WebSocket — see shutdown_state.
+        timeout_graceful_shutdown=GRACEFUL_SHUTDOWN_TIMEOUT,
     )

server/src/ledgrab/shutdown_state.py

@@ -16,3 +16,15 @@ they release Windows / unblock only once cleanup is genuinely done.
 import threading
 
 shutdown_complete: threading.Event = threading.Event()
+
+# Bound uvicorn's graceful-shutdown wait (``uvicorn.Config(timeout_graceful_shutdown=...)``).
+# uvicorn defaults this to ``None`` — ``Server.shutdown()`` then waits *forever*
+# for open connections (and their tasks) to drain before it runs the lifespan
+# shutdown. The events WebSocket handler blocks on ``queue.get()`` and the
+# browser auto-reconnects, so connections never drain on their own. Without a
+# bound, the lifespan shutdown — which stops LED targets and checkpoints the
+# DB — never runs: targets stay lit and the process can't exit (leftover
+# processor threads). Shared by both the desktop (__main__) and Android
+# (android_entry) launchers. Keep it small so OS-shutdown cleanup still fits
+# Windows' ~20 s budget; it is spent BEFORE the lifespan's own ~16 s budget.
+GRACEFUL_SHUTDOWN_TIMEOUT: int = 3

server/src/ledgrab/static/css/automations.css

@@ -74,6 +74,19 @@
     font-size: 0.85rem;
 }
 
+/* Android-only: shown in the application rule when Usage Access is missing,
+   so the foreground-app rule can't fire until the user grants it on the TV. */
+.rule-usage-warning {
+    margin-bottom: 10px;
+    padding: 8px 12px;
+    border-radius: 6px;
+    font-size: 0.85rem;
+    line-height: 1.35;
+    color: var(--warning-color, #ff9800);
+    background: color-mix(in srgb, var(--warning-color, #ff9800) 12%, transparent);
+    border: 1px solid color-mix(in srgb, var(--warning-color, #ff9800) 35%, transparent);
+}
+
 .btn-remove-rule {
     background: none;
     border: none;

server/src/ledgrab/static/css/components.css

@@ -298,6 +298,214 @@ select.field-invalid {
     line-height: 1.3;
 }
 
+.field-ok-msg {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    color: var(--success-color);
+    font-size: 0.78rem;
+    margin-top: 4px;
+    line-height: 1.3;
+}
+
+.field-ok-msg .icon { width: 14px; height: 14px; }
+.field-error-msg .icon { width: 14px; height: 14px; vertical-align: -2px; margin-right: 3px; }
+
+.field-warn-msg {
+    display: block;
+    color: var(--text-muted);
+    font-size: 0.76rem;
+    margin-top: 4px;
+    line-height: 1.35;
+}
+
+/* ── Jinja expression editor ─────────────────────────────────────
+   A transparent <textarea> layered over a synced highlight <pre>.
+   Both share identical type metrics so the colour layer aligns with
+   the typed glyphs. The shared box rules below MUST stay in sync. */
+.jinja-editor {
+    position: relative;
+    display: block;
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-sm);
+    background: var(--surface-2, color-mix(in srgb, var(--text-color) 6%, var(--bg-color)));
+    overflow: hidden;
+    transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.jinja-editor:focus-within {
+    border-color: var(--primary-color);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--primary-color) 18%, transparent);
+}
+
+.jinja-editor.field-invalid {
+    border-color: var(--danger-color);
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--danger-color) 15%, transparent);
+}
+
+/* Shared metrics — applied identically to both layers. */
+.jinja-hl,
+.jinja-input {
+    margin: 0;
+    padding: 10px 12px;
+    font-family: var(--font-mono);
+    font-size: 0.86rem;
+    line-height: 1.55;
+    letter-spacing: 0;
+    tab-size: 2;
+    white-space: pre;
+    word-wrap: normal;
+    overflow: auto;
+    box-sizing: border-box;
+}
+
+.jinja-hl {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    color: var(--text-color);
+    overflow: hidden;       /* scroll is mirrored from the textarea */
+    user-select: none;
+}
+
+.jinja-input {
+    position: relative;
+    display: block;
+    width: 100%;
+    min-height: 4.6em;       /* ~3 lines */
+    resize: vertical;
+    border: none;
+    background: transparent;
+    color: transparent;      /* glyphs are painted by .jinja-hl underneath */
+    caret-color: var(--text-color);
+    outline: none;
+}
+
+/* The global `textarea:focus` rule (higher specificity than `.jinja-input`)
+   sets an opaque background; on this overlay editor that would cover the
+   `.jinja-hl` highlight layer and hide the transparent glyphs on focus. Keep
+   the textarea fully transparent — the focus ring is drawn by the wrapper's
+   `.jinja-editor:focus-within`. */
+.jinja-input:focus {
+    background: transparent;
+    color: transparent;
+    box-shadow: none;
+}
+
+.jinja-input::selection { background: color-mix(in srgb, var(--primary-color) 30%, transparent); }
+
+/* Token palette — restrained, three accents plus muted operators. */
+.jinja-hl .tok-str { color: var(--success-color); }
+.jinja-hl .tok-num { color: #d19a66; }
+.jinja-hl .tok-fn  { color: var(--primary-color); font-weight: 600; }
+.jinja-hl .tok-raw { color: #c678dd; font-style: italic; }
+.jinja-hl .tok-var { color: #61afef; }
+.jinja-hl .tok-op  { color: var(--text-muted); }
+
+/* ── Template-input rows ─────────────────────────────────────── */
+.template-inputs-list {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    margin-bottom: 8px;
+}
+
+.template-input-row {
+    display: grid;
+    grid-template-columns: minmax(96px, 0.42fr) minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 8px;
+}
+
+.template-input-name {
+    font-family: var(--font-mono);
+    font-size: 0.84rem;
+}
+
+.template-input-row .entity-select-trigger { width: 100%; }
+
+.template-inputs-empty {
+    color: var(--text-muted);
+    font-size: 0.82rem;
+    padding: 6px 2px;
+}
+
+/* ── Expression hints panel ──────────────────────────────────── */
+.jinja-hints {
+    margin-top: 10px;
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-sm);
+    background: color-mix(in srgb, var(--text-color) 3%, transparent);
+}
+
+.jinja-hints > summary {
+    cursor: pointer;
+    list-style: none;
+    padding: 8px 12px;
+    font-size: 0.8rem;
+    font-weight: 600;
+    color: var(--text-secondary);
+    user-select: none;
+}
+
+.jinja-hints > summary::-webkit-details-marker { display: none; }
+.jinja-hints > summary::before {
+    content: '›';
+    display: inline-block;
+    margin-right: 6px;
+    transition: transform 0.15s ease;
+    color: var(--text-muted);
+}
+.jinja-hints[open] > summary::before { transform: rotate(90deg); }
+
+.jinja-hints-body {
+    padding: 4px 14px 12px;
+    font-size: 0.8rem;
+    line-height: 1.5;
+    color: var(--text-secondary);
+}
+
+.jinja-hints-body code,
+.jinja-hints-body .jinja-hints-vars code {
+    font-family: var(--font-mono);
+    font-size: 0.78rem;
+    padding: 1px 5px;
+    border-radius: var(--radius-sm);
+    background: color-mix(in srgb, var(--text-color) 8%, transparent);
+    color: var(--text-color);
+}
+
+.jinja-hints-section { margin-top: 8px; }
+.jinja-hints-section-title {
+    display: block;
+    font-size: 0.72rem;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--text-muted);
+    margin-bottom: 3px;
+}
+
+.jinja-hints-vars {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 5px;
+}
+
+.jinja-hints-vars .tok-var-chip {
+    font-family: var(--font-mono);
+    font-size: 0.76rem;
+    padding: 1px 6px;
+    border-radius: var(--radius-pill);
+    background: color-mix(in srgb, #61afef 16%, transparent);
+    color: #61afef;
+}
+
+.jinja-hints-examples { margin: 4px 0 0; padding-left: 0; list-style: none; }
+.jinja-hints-examples li { margin: 3px 0; }
+
+.jinja-hints-empty { color: var(--text-muted); font-size: 0.76rem; font-style: italic; }
+.jinja-hints-time { color: var(--text-muted); font-size: 0.76rem; }
+
 /* Remove browser autofill styling */
 input:-webkit-autofill,
 input:-webkit-autofill:hover,

server/src/ledgrab/static/css/graph-editor.css

@@ -495,6 +495,18 @@ html:has(#tab-graph.active) {
     opacity: 0.95;
 }
 
+/* Custom per-entity icon: the embedded SVG strokes with currentColor, so it is
+   tinted via `color` (default muted; the node's icon_color overrides inline). */
+.graph-node-custom-icon {
+    color: var(--lux-ink-mute, var(--text-muted));
+    opacity: 0.9;
+}
+
+.graph-node.running .graph-node-custom-icon {
+    color: var(--ch-signal, var(--primary-color));
+    opacity: 1;
+}
+
 /* ── Running indicator (animated gradient border + signal-flow glow) ── */
 
 .graph-node.running .graph-node-body {
@@ -588,6 +600,21 @@ html:has(#tab-graph.active) {
     filter: drop-shadow(0 0 6px var(--ch-signal, var(--primary-color)));
 }
 
+/* Whole-node drop targets: a source can be dropped on any compatible node to
+   wire one of its slots — including empty slots that have no input port yet. */
+.graph-svg.connecting .graph-node-compatible .graph-node-body {
+    stroke: var(--ch-signal, var(--primary-color));
+    stroke-dasharray: 4 3;
+    stroke-width: 1.5;
+}
+
+.graph-node-drop-target .graph-node-body {
+    stroke: var(--ch-signal, var(--primary-color)) !important;
+    stroke-width: 2.5 !important;
+    stroke-dasharray: none !important;
+    filter: drop-shadow(0 0 8px color-mix(in srgb, var(--ch-signal, var(--primary-color)) 55%, transparent));
+}
+
 /* ── Edges ── */
 
 .graph-edge {
@@ -630,6 +657,25 @@ html:has(#tab-graph.active) {
     opacity: 0.4;
 }
 
+/* Edge field labels — hidden until zoomed in enough to read them. */
+.graph-edge-label {
+    font-size: 9px;
+    font-weight: 600;
+    font-family: var(--font-mono, monospace);
+    fill: var(--text-secondary);
+    paint-order: stroke;
+    stroke: var(--lux-bg-1, var(--card-bg));
+    stroke-width: 3px;
+    stroke-linejoin: round;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.15s ease;
+}
+
+.graph-edges.show-labels .graph-edge-label {
+    opacity: 0.85;
+}
+
 /* Edge type colors */
 .graph-edge-picture    { stroke: #42A5F5; color: #42A5F5; }
 .graph-edge-colorstrip { stroke: #66BB6A; color: #66BB6A; }
@@ -788,6 +834,17 @@ html:has(#tab-graph.active) {
     stroke-dasharray: 4 3;
 }
 
+/* ── Health overlay: configuration issues (broken refs / cycles) ── */
+.graph-node.has-issue .graph-node-body {
+    stroke: var(--danger-color);
+    stroke-width: 2;
+    stroke-dasharray: 5 3;
+}
+
+.graph-node-issue {
+    color: var(--danger-color);
+}
+
 /* ── Search highlight ── */
 
 .graph-node.search-match .graph-node-body {
@@ -1001,6 +1058,33 @@ html:has(#tab-graph.active) {
     display: inline-block;
 }
 
+/* Issues toolbar button + count badge */
+.graph-issues-btn {
+    position: relative;
+    color: var(--danger-color);
+}
+
+.graph-issues-count {
+    position: absolute;
+    top: 0;
+    right: 0;
+    transform: translate(35%, -35%);
+    background: var(--danger-color);
+    color: #fff;
+    border-radius: 8px;
+    font-size: 0.6rem;
+    font-weight: 700;
+    min-width: 14px;
+    height: 14px;
+    line-height: 14px;
+    text-align: center;
+    padding: 0 3px;
+}
+
+.graph-issues-count:empty {
+    display: none;
+}
+
 .graph-filter-types-popover {
     display: none;
     flex-direction: column;

server/src/ledgrab/static/js/app.ts

@@ -184,9 +184,11 @@ import {
     showValueSourceModal, closeValueSourceModal, saveValueSource,
     editValueSource, cloneValueSource, deleteValueSource, onValueSourceTypeChange,
     onDaylightVSRealTimeChange,
+    onValueSourceNormalizeChange,
     addSchedulePoint,
     addAnimatedColor, removeAnimatedColor,
     addColorSchedulePoint, removeColorSchedulePoint,
+    addTemplateInput,
     testValueSource, closeTestValueSourceModal,
 } from './features/value-sources.ts';
 
@@ -207,7 +209,7 @@ import {
 import {
     loadGraphEditor,
     toggleGraphLegend, toggleGraphMinimap, toggleGraphFilter, toggleGraphFilterTypes, toggleGraphHelp, graphUndo, graphRedo,
-    graphFitAll, graphZoomIn, graphZoomOut, graphRelayout,
+    graphFitAll, graphZoomIn, graphZoomOut, graphRelayout, graphShowIssues, graphExportTopology, graphDuplicateSelection,
     graphToggleFullscreen, graphAddEntity, toggleToolbarOverflow, closeToolbarOverflow,
 } from './features/graph-editor.ts';
 
@@ -579,11 +581,13 @@ Object.assign(window, {
     deleteValueSource,
     onValueSourceTypeChange,
     onDaylightVSRealTimeChange,
+    onValueSourceNormalizeChange,
     addSchedulePoint,
     addAnimatedColor,
     removeAnimatedColor,
     addColorSchedulePoint,
     removeColorSchedulePoint,
+    addTemplateInput,
     testValueSource,
     closeTestValueSourceModal,
 
@@ -625,6 +629,9 @@ Object.assign(window, {
     graphZoomIn,
     graphZoomOut,
     graphRelayout,
+    graphShowIssues,
+    graphExportTopology,
+    graphDuplicateSelection,
     graphToggleFullscreen,
     graphAddEntity,
     toggleToolbarOverflow,

server/src/ledgrab/static/js/core/graph-connections.ts

@@ -3,11 +3,128 @@
  * Supports creating, changing, and detaching connections via the graph editor.
  */
 
-import { apiPut } from './api-client.ts';
+import { apiPut, apiPost, apiGet } from './api-client.ts';
 import {
     streamsCache, colorStripSourcesCache, valueSourcesCache,
     audioSourcesCache, outputTargetsCache, automationsCacheObj,
 } from './state.ts';
+import { logError } from './log.ts';
+
+/** Result of the backend pre-write connection validator. */
+export interface ConnectionValidation {
+    ok: boolean;
+    error?: string | null;
+}
+
+/**
+ * Ask the backend whether a proposed wiring edit is valid (target/source exist,
+ * source is the right kind, and it would not create a dependency cycle).
+ *
+ * Fails *open*: if the validation endpoint is unavailable we return ``ok`` so
+ * wiring still works against older servers — the per-entity PUT remains the
+ * source of truth, this is just an early, friendlier guard.
+ */
+export async function validateConnection(
+    targetKind: string, targetId: string, field: string, sourceId: string,
+): Promise<ConnectionValidation> {
+    try {
+        return await apiPost<ConnectionValidation>('/graph/validate-connection', {
+            target_kind: targetKind,
+            target_id: targetId,
+            field,
+            source_id: sourceId,
+        });
+    } catch {
+        return { ok: true };
+    }
+}
+
+/** An entity that references another entity (one row of the dependents query). */
+export interface GraphDependent {
+    id: string;
+    kind: string;
+    name: string;
+    field: string;
+}
+
+/**
+ * List every entity that references ``(kind, id)``. Used to warn before a
+ * delete would dangle other entities' references. Fails *safe* (empty list)
+ * if the endpoint is unavailable.
+ */
+export async function getDependents(kind: string, id: string): Promise<GraphDependent[]> {
+    try {
+        const res = await apiGet<{ dependents: GraphDependent[] }>(
+            `/graph/dependents/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`,
+        );
+        return res.dependents || [];
+    } catch {
+        return [];
+    }
+}
+
+/* ── Schema drift guard (B4) ───────────────────────────────────── */
+
+// Backend-declared reference fields the frontend intentionally does NOT drag-edit
+// (the backend still lists them for topology/dependents completeness, so the drift
+// check ignores them). Two categories:
+//   (a) the source kind is not a graph node — nothing to drag from.
+//   (b) the owning entity's PUT route is not safely partial-writable via a single
+//       dragged field, so it's edited through the entity editor instead.
+const _DRIFT_EXCLUDE = new Set<string>([
+    // (a) no graph node for the source kind — nothing to drag from:
+    'value_source|ha_source_id',
+    'value_source|gradient_id',
+    // (b) not safely partial-PUT-able from a single dragged field:
+    'device|default_css_processing_template_id', // a one-field device PUT could null the URL
+    // (c) editable in principle but not surfaced as a graph edge yet:
+    'value_source|clock_id', // sync_clock → animated_colour value-source timing
+]);
+
+let _driftChecked = false;
+
+interface SchemaConnection { target_kind: string; field: string; editable: boolean; }
+
+/**
+ * Dev safety net for the B4 finding: warn once if the frontend CONNECTION_MAP's
+ * editable set diverges from the backend `/graph/schema` (the drift the manual
+ * "10-step checklist" guards against). Read-only — never affects the graph.
+ * No-op against older servers without the endpoint.
+ *
+ * Note: this references `CONNECTION_MAP` (const) and `_isEditable` (fn) declared
+ * later in the module — safe because it is only ever invoked at runtime (from
+ * `loadGraphEditor`), well after module initialization.
+ */
+export async function checkSchemaDrift(): Promise<void> {
+    if (_driftChecked) return;
+    _driftChecked = true;
+
+    let connections: SchemaConnection[];
+    try {
+        connections = (await apiGet<{ connections: SchemaConnection[] }>('/graph/schema')).connections || [];
+    } catch {
+        return;  // endpoint unavailable — nothing to compare against
+    }
+
+    const k = (kind: string, field: string): string => `${kind}|${field}`;
+    const backend = new Set<string>();
+    for (const c of connections) {
+        if (c.editable && !_DRIFT_EXCLUDE.has(k(c.target_kind, c.field))) backend.add(k(c.target_kind, c.field));
+    }
+    const frontend = new Set<string>();
+    for (const c of CONNECTION_MAP) {
+        if (_isEditable(c) && !_DRIFT_EXCLUDE.has(k(c.targetKind, c.field))) frontend.add(k(c.targetKind, c.field));
+    }
+
+    const missingOnFrontend = [...backend].filter(key => !frontend.has(key));
+    const missingOnBackend = [...frontend].filter(key => !backend.has(key));
+    if (missingOnFrontend.length || missingOnBackend.length) {
+        logError('graph.schema_drift', new Error(
+            `CONNECTION_MAP drift vs /graph/schema — editable fields missing on frontend: ` +
+            `[${missingOnFrontend.join(', ')}]; missing on backend: [${missingOnBackend.join(', ')}]`,
+        ));
+    }
+}
 
 /* ── Types ────────────────────────────────────────────────────── */
 
@@ -19,6 +136,13 @@ interface ConnectionEntry {
     endpoint?: string;
     cache?: { invalidate(): void };
     nested?: boolean;
+    /**
+     * A single-level value-source binding (e.g. `brightness.source_id`). These
+     * are structurally nested but ARE drag-editable: the write goes through the
+     * entity's `BindableFloat.apply_update`, which merges `{source_id}` while
+     * preserving the static value. (List/double-nested fields stay read-only.)
+     */
+    bindable?: boolean;
 }
 
 interface CompatibleInput {
@@ -52,35 +176,42 @@ const CONNECTION_MAP: ConnectionEntry[] = [
     { targetKind: 'value_source', field: 'value_source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/value-sources/{id}', cache: valueSourcesCache },
     { targetKind: 'value_source', field: 'gradient_id', sourceKind: 'gradient', edgeType: 'gradient', endpoint: '/value-sources/{id}', cache: valueSourcesCache },
     { targetKind: 'value_source', field: 'color_strip_source_id', sourceKind: 'color_strip_source', edgeType: 'colorstrip', endpoint: '/value-sources/{id}', cache: valueSourcesCache },
+    // TODO: template.inputs[] drag-wiring — template value sources reference one
+    // inner value source per bound input (field path inputs[<name>].value_source_id).
+    // These render as read-only 'value' edges in graph-layout for now; a list-aware
+    // CONNECTION_MAP entry (with list/index/ref slot metadata) would make them
+    // re-wirable from the graph the way composite layers / mapped zones are.
 
     // Color strip sources
     { targetKind: 'color_strip_source', field: 'picture_source_id', sourceKind: 'picture_source', edgeType: 'picture', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
     { targetKind: 'color_strip_source', field: 'audio_source_id', sourceKind: 'audio_source', edgeType: 'audio', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
     { targetKind: 'color_strip_source', field: 'clock_id', sourceKind: 'sync_clock', edgeType: 'clock', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
+    // Processed strip: input source + processing template (apply_update is partial-safe)
+    { targetKind: 'color_strip_source', field: 'input_source_id', sourceKind: 'color_strip_source', edgeType: 'colorstrip', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
+    { targetKind: 'color_strip_source', field: 'processing_template_id', sourceKind: 'cspt', edgeType: 'template', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
 
     // Output targets
     { targetKind: 'output_target', field: 'device_id', sourceKind: 'device', edgeType: 'device', endpoint: '/output-targets/{id}', cache: outputTargetsCache },
     { targetKind: 'output_target', field: 'color_strip_source_id', sourceKind: 'color_strip_source', edgeType: 'colorstrip', endpoint: '/output-targets/{id}', cache: outputTargetsCache },
-    { targetKind: 'output_target', field: 'brightness.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/output-targets/{id}', cache: outputTargetsCache, nested: true },
+    { targetKind: 'output_target', field: 'brightness.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/output-targets/{id}', cache: outputTargetsCache, nested: true, bindable: true },
-    { targetKind: 'output_target', field: 'picture_source_id', sourceKind: 'picture_source', edgeType: 'picture', endpoint: '/output-targets/{id}', cache: outputTargetsCache },
 
     // Automations
     { targetKind: 'automation', field: 'scene_preset_id', sourceKind: 'scene_preset', edgeType: 'scene', endpoint: '/automations/{id}', cache: automationsCacheObj },
     { targetKind: 'automation', field: 'deactivation_scene_preset_id', sourceKind: 'scene_preset', edgeType: 'scene', endpoint: '/automations/{id}', cache: automationsCacheObj },
 
-    // ── BindableFloat value source edges (CSS properties) ──
+    // ── BindableFloat value source edges (CSS properties) — drag-editable ──
-    { targetKind: 'color_strip_source', field: 'smoothing.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'smoothing.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'sensitivity.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'sensitivity.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'intensity.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'intensity.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'scale.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'scale.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'speed.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'speed.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'wind_strength.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'wind_strength.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'temperature_influence.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'temperature_influence.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'sound_volume.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'sound_volume.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'timeout.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'timeout.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
-    { targetKind: 'color_strip_source', field: 'brightness.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'color_strip_source', field: 'brightness.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache, nested: true, bindable: true },
     // HA light target transition binding
-    { targetKind: 'output_target', field: 'transition.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
+    { targetKind: 'output_target', field: 'transition.source_id', sourceKind: 'value_source', edgeType: 'value', endpoint: '/output-targets/{id}', cache: outputTargetsCache, nested: true, bindable: true },
     // ── BindableColor value source edges (CSS color properties) ──
     { targetKind: 'color_strip_source', field: 'color.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
     { targetKind: 'color_strip_source', field: 'color_peak.source_id', sourceKind: 'value_source', edgeType: 'value', nested: true },
@@ -97,12 +228,23 @@ const CONNECTION_MAP: ConnectionEntry[] = [
     { targetKind: 'scene_preset', field: 'target_id', sourceKind: 'output_target', edgeType: 'scene', nested: true },
 ];
 
+/** Editable via the graph: top-level reference fields, plus single-level
+ *  bindable value-source slots (list/double-nested fields stay read-only). */
+function _isEditable(c: ConnectionEntry): boolean {
+    return !c.nested || !!c.bindable;
+}
+
+/** True when a field is a bindable slot (its parent is a `Bindable*`). */
+export function isBindableField(targetKind: string, field: string): boolean {
+    return !!CONNECTION_MAP.find(c => c.targetKind === targetKind && c.field === field)?.bindable;
+}
+
 /**
  * Check if an edge (by field name) is editable via drag-connect.
  */
 export function isEditableEdge(field: string): boolean {
     const entry = CONNECTION_MAP.find(c => c.field === field);
-    return entry ? !entry.nested : false;
+    return entry ? _isEditable(entry) : false;
 }
 
 /**
@@ -111,7 +253,7 @@ export function isEditableEdge(field: string): boolean {
  */
 export function findConnection(targetKind: string, sourceKind: string, edgeType?: string): ConnectionEntry[] {
     return CONNECTION_MAP.filter(c =>
-        !c.nested &&
+        _isEditable(c) &&
         c.targetKind === targetKind &&
         c.sourceKind === sourceKind &&
         (!edgeType || c.edgeType === edgeType)
@@ -124,7 +266,7 @@ export function findConnection(targetKind: string, sourceKind: string, edgeType?
  */
 export function getCompatibleInputs(sourceKind: string): CompatibleInput[] {
     return CONNECTION_MAP
-        .filter(c => !c.nested && c.sourceKind === sourceKind)
+        .filter(c => _isEditable(c) && c.sourceKind === sourceKind)
         .map(c => ({ targetKind: c.targetKind, field: c.field, edgeType: c.edgeType }));
 }
 
@@ -132,9 +274,28 @@ export function getCompatibleInputs(sourceKind: string): CompatibleInput[] {
  * Find the connection entry for a specific edge (by target kind and field).
  */
 export function getConnectionByField(targetKind: string, field: string): ConnectionEntry | undefined {
-    return CONNECTION_MAP.find(c => c.targetKind === targetKind && c.field === field && !c.nested);
+    return CONNECTION_MAP.find(c => c.targetKind === targetKind && c.field === field && _isEditable(c));
 }
 
+/**
+ * Entity kinds whose per-entity PUT route validates the body against a Pydantic
+ * **discriminated union** (`Body(discriminator=...)`). Such a route 422s unless
+ * the body echoes the discriminator field, so a partial wiring write (just a
+ * reference field) is rejected outright. Maps the target kind → the
+ * discriminator's body-field name; the value is the target's *current* subtype,
+ * which we read back from the entity immediately before the write.
+ *
+ * Without this, drag-to-wire silently fails for nearly every source kind. Keep
+ * in sync with the backend `NODE_TYPE_FIELD` map in `api/graph_schema.py`.
+ */
+const _DISCRIMINATOR_FIELD: Readonly<Record<string, string>> = {
+    picture_source: 'stream_type',
+    audio_source: 'source_type',
+    value_source: 'source_type',
+    color_strip_source: 'source_type',
+    output_target: 'target_type',
+};
+
 /**
  * Update a connection: set the reference field on the target entity.
  * @param {string} targetId - The target entity's ID
@@ -144,11 +305,31 @@ export function getConnectionByField(targetKind: string, field: string): Connect
  * @returns {Promise<boolean>} success
  */
 export async function updateConnection(targetId: string, targetKind: string, field: string, newSourceId: string | null): Promise<boolean> {
-    const entry = CONNECTION_MAP.find(c => c.targetKind === targetKind && c.field === field && !c.nested);
+    const entry = CONNECTION_MAP.find(c => c.targetKind === targetKind && c.field === field && _isEditable(c));
-    if (!entry) return false;
+    if (!entry || !entry.endpoint) return false;
 
-    const url = entry.endpoint!.replace('{id}', targetId);
+    const url = entry.endpoint.replace('{id}', targetId);
-    const body = { [field]: newSourceId };
+    // For a bindable slot (`<parent>.source_id`) PUT `{ <parent>: { source_id } }`
+    // so the backend's `Bindable*.apply_update` merges and preserves the static
+    // value/colour. Top-level fields keep the flat `{ field: id }` shape.
+    const body: Record<string, unknown> = entry.bindable
+        ? { [field.split('.')[0]]: { source_id: newSourceId || '' } }
+        : { [field]: newSourceId };
+
+    // Discriminated-union PUT routes reject a body without their discriminator.
+    // Echo the target's current subtype so a partial wiring write validates
+    // instead of 422-ing. Best-effort: a failed read leaves the PUT to fail as
+    // before — it never makes things worse.
+    const discrimField = _DISCRIMINATOR_FIELD[targetKind];
+    if (discrimField) {
+        try {
+            const current = await apiGet<Record<string, unknown>>(url);
+            const tag = current?.[discrimField];
+            if (typeof tag === 'string' && tag) body[discrimField] = tag;
+        } catch {
+            /* leave body as-is; the PUT below will surface any error */
+        }
+    }
 
     try {
         await apiPut(url, body);
@@ -167,4 +348,115 @@ export async function detachConnection(targetId: string, targetKind: string, fie
     return updateConnection(targetId, targetKind, field, '');
 }
 
+/* ── List-element slots (composite layers / mapped zones) ──────────── */
+
+/**
+ * Targets that hold *list* reference slots. Editing one element means
+ * re-PUTting the whole list, so we map the kind → its endpoint + cache.
+ * (Only color strip sources have list slots today: composite `layers`,
+ * mapped `zones`.)
+ */
+const _LIST_SLOT_TARGET: Readonly<Record<string, { endpoint: string; cache: { invalidate(): void } }>> = {
+    color_strip_source: { endpoint: '/color-strip-sources/{id}', cache: colorStripSourcesCache },
+};
+
+/**
+ * Re-wire a single element of a list reference slot — e.g. a composite
+ * `layers[index].source_id` or a mapped `zones[index].source_id`.
+ *
+ * The owning entity's PUT replaces the *entire* list, so this reads the entity
+ * back, copies every element verbatim, changes only `list[index][refField]`,
+ * and PUTs the full list (plus the discriminator). Echoing the existing element
+ * objects is what preserves each layer/zone's other settings (blend mode,
+ * opacity, LED range, per-layer brightness/template, …) — a naive partial write
+ * would silently drop that config.
+ *
+ * @param newSourceId New source id, or '' to clear (only valid for optional refs).
+ * @returns Promise<boolean> success
+ */
+export async function updateListSlotConnection(
+    targetId: string,
+    targetKind: string,
+    listField: string,
+    index: number,
+    refField: string,
+    newSourceId: string | null,
+    expectedCurrent?: string | null,
+): Promise<boolean> {
+    const target = _LIST_SLOT_TARGET[targetKind];
+    if (!target || !Number.isInteger(index) || index < 0) return false;
+
+    const url = target.endpoint.replace('{id}', targetId);
+    try {
+        const current = await apiGet<Record<string, unknown>>(url);
+        const list = current?.[listField];
+        if (!Array.isArray(list) || index >= list.length) return false;
+
+        // Optimistic-concurrency guard: `index` is positional, so if the list was
+        // reordered/edited out-of-band (e.g. via the entity editor) between render
+        // and write — or between an action and its undo/redo — that index now points
+        // at a *different* element. Refuse rather than rewrite the wrong slot.
+        if (expectedCurrent != null) {
+            const el = list[index] as Record<string, unknown>;
+            const actual = typeof el?.[refField] === 'string' ? (el[refField] as string) : '';
+            if (actual !== expectedCurrent) return false;
+        }
+
+        // Copy every element; change only the one ref on the targeted element.
+        // (`|| ''` clears the ref — only valid for *optional* refs; the graph only
+        // re-wires the required `source_id`, so callers always pass a real id here.)
+        const nextList = list.map((el, i) =>
+            i === index
+                ? { ...(el as Record<string, unknown>), [refField]: newSourceId || '' }
+                : { ...(el as Record<string, unknown>) },
+        );
+        const body: Record<string, unknown> = { [listField]: nextList };
+
+        // Discriminated-union PUT routes need the subtype echoed (see updateConnection).
+        const discrimField = _DISCRIMINATOR_FIELD[targetKind];
+        if (discrimField) {
+            const tag = current[discrimField];
+            if (typeof tag === 'string' && tag) body[discrimField] = tag;
+        }
+
+        await apiPut(url, body);
+        target.cache.invalidate();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/* ── Subgraph duplication (D6) ─────────────────────────────────────── */
+
+/** Result of `POST /graph/duplicate` (server-side clone of a selected subgraph). */
+export interface DuplicateResult {
+    id_map: Record<string, string>;
+    created: Array<{ id: string; kind: string; name: string }>;
+    skipped: Array<{ id: string; reason: string }>;
+    warnings: Array<{ id: string; reason: string }>;
+}
+
+/**
+ * Server-side duplicate of a selected subgraph: the backend deep-clones the
+ * value / colour-strip sources among `nodeIds` with fresh ids and rewires
+ * references that point *within* the selection (shared deps stay shared).
+ * Returns the result, or `null` on failure. Invalidates the affected caches so
+ * a subsequent graph reload shows the clones.
+ */
+export async function duplicateSubgraph(
+    nodeIds: string[], nameSuffix?: string,
+): Promise<DuplicateResult | null> {
+    try {
+        const body: Record<string, unknown> = { node_ids: nodeIds };
+        if (nameSuffix) body.name_suffix = nameSuffix;
+        const res = await apiPost<DuplicateResult>('/graph/duplicate', body);
+        valueSourcesCache.invalidate();
+        colorStripSourcesCache.invalidate();
+        return res;
+    } catch {
+        return null;
+    }
+}
+
 export { CONNECTION_MAP };

server/src/ledgrab/static/js/core/graph-edges.ts

@@ -19,6 +19,9 @@ interface GraphEdge {
     type: string;
     field?: string;
     editable?: boolean;
+    /** List-element reference (composite layer / mapped zone) — exposed as
+     *  `data-slot-*` so the editor can re-wire just this slot. */
+    slot?: { list: string; index: number; ref: string };
     points?: { x: number; y: number }[] | null;
     fromNode?: GraphNodeRect;
     toNode?: GraphNodeRect;
@@ -52,6 +55,43 @@ export function renderEdges(group: SVGGElement, edges: GraphEdge[]): void {
         const path = _renderEdge(edge);
         group.appendChild(path);
     }
+
+    // Field labels rendered last so they sit above the paths. Hidden by
+    // default — revealed when zoomed in (`.show-labels`) or on highlight.
+    for (const edge of edges) {
+        const label = _renderEdgeLabel(edge);
+        if (label) group.appendChild(label);
+    }
+}
+
+/** Human-readable label for a reference field, e.g. `capture_template_id` → `capture template`. */
+function _edgeFieldLabel(field: string): string {
+    return field.replace(/_id$/, '').replace(/\./g, ' ').replace(/_/g, ' ').trim();
+}
+
+/** Midpoint of the port-aware cubic bezier (its control points are horizontal
+ *  offsets only, so the t=0.5 point is exactly the endpoint midpoint). */
+function _edgeMidpoint(fromNode: GraphNodeRect, toNode: GraphNodeRect, fromPortY?: number, toPortY?: number): { x: number; y: number } {
+    const x1 = fromNode.x + fromNode.width;
+    const y1 = fromNode.y + (fromPortY ?? fromNode.height / 2);
+    const x2 = toNode.x;
+    const y2 = toNode.y + (toPortY ?? toNode.height / 2);
+    return { x: (x1 + x2) / 2, y: (y1 + y2) / 2 };
+}
+
+function _renderEdgeLabel(edge: GraphEdge): SVGElement | null {
+    if (!edge.field || !edge.fromNode || !edge.toNode) return null;
+    const mid = _edgeMidpoint(edge.fromNode, edge.toNode, edge.fromPortY, edge.toPortY);
+    const text = svgEl('text', {
+        class: `graph-edge-label graph-edge-label-${edge.type}`,
+        x: mid.x, y: mid.y - 4,
+        'text-anchor': 'middle',
+        'data-from': edge.from,
+        'data-to': edge.to,
+        'data-field': edge.field,
+    });
+    text.textContent = _edgeFieldLabel(edge.field);
+    return text;
 }
 
 function _createArrowMarker(type: string): SVGElement {
@@ -87,6 +127,12 @@ function _renderEdge(edge: GraphEdge): SVGElement {
         'data-to': to,
         'data-field': field || '',
     });
+    // List-element reference: expose the slot so the editor can re-wire it.
+    if (edge.slot) {
+        path.setAttribute('data-slot-list', edge.slot.list);
+        path.setAttribute('data-slot-index', String(edge.slot.index));
+        path.setAttribute('data-slot-ref', edge.slot.ref);
+    }
 
     // Tooltip
     const title = svgEl('title');
@@ -263,6 +309,14 @@ export function updateEdgesForNode(group: SVGGElement, nodeId: string, nodeMap:
                 pathEl.setAttribute('d', d);
             }
         });
+        // Keep the field label pinned to the edge midpoint while dragging.
+        const mid = _edgeMidpoint(fromNode, toNode, edge.fromPortY, edge.toPortY);
+        group.querySelectorAll(`.graph-edge-label[data-from="${edge.from}"][data-to="${edge.to}"]`).forEach(lbl => {
+            if ((lbl.getAttribute('data-field') || '') === (edge.field || '')) {
+                lbl.setAttribute('x', String(mid.x));
+                lbl.setAttribute('y', String(mid.y - 4));
+            }
+        });
     }
 }
 

server/src/ledgrab/static/js/core/graph-layout.ts

@@ -13,6 +13,8 @@ interface LayoutNode {
     name: string;
     subtype: string;
     tags: string[];
+    icon?: string;
+    iconColor?: string;
     running?: boolean;
     x?: number;
     y?: number;
@@ -27,12 +29,27 @@ interface LayoutEdge {
     label: string;
     type: string;
     editable: boolean;
+    /** For list-element references (composite layers / mapped zones): which list,
+     *  which element index, and the reference field on that element. Lets the
+     *  editor re-wire one slot without disturbing its siblings. */
+    slot?: { list: string; index: number; ref: string };
 }
 
 interface LayoutResult {
     nodes: Map<string, LayoutNode>;
     edges: (LayoutEdge & { points: { x: number; y: number }[] | null; fromNode: LayoutNode; toNode: LayoutNode })[];
     bounds: { x: number; y: number; width: number; height: number };
+    brokenRefs: BrokenRef[];
+}
+
+/** A reference field that points at an entity which no longer exists. */
+export interface BrokenRef {
+    /** The missing (referenced) entity id. */
+    ref: string;
+    /** The id of the entity that still holds the dangling reference. */
+    by: string;
+    /** The reference field name on the referrer. */
+    field: string;
 }
 
 interface PortSet {
@@ -81,7 +98,7 @@ const ELK_OPTIONS = {
  */
 export async function computeLayout(entities: EntitiesInput): Promise<LayoutResult> {
     const elk = new ELK();
-    const { nodes: nodeList, edges: edgeList } = buildGraph(entities);
+    const { nodes: nodeList, edges: edgeList, brokenRefs } = buildGraph(entities);
 
     const elkGraph = {
         id: 'root',
@@ -151,7 +168,7 @@ export async function computeLayout(entities: EntitiesInput): Promise<LayoutResu
         ? { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
         : { x: 0, y: 0, width: 400, height: 300 };
 
-    return { nodes: nodeMap, edges, bounds };
+    return { nodes: nodeMap, edges, bounds, brokenRefs };
 }
 
 /* ── Entity color mapping ── */
@@ -207,97 +224,113 @@ function edgeType(fromKind: string, toKind: string, field: string): string {
 
 /* ── Graph builder ── */
 
-function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[] } {
+function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[]; brokenRefs: BrokenRef[] } {
     const nodes: LayoutNode[] = [];
     const edges: LayoutEdge[] = [];
+    const brokenRefs: BrokenRef[] = [];
     const nodeIds = new Set<string>();
+    // Index nodes by id so edge-building is O(1) instead of O(N) per edge.
+    const nodeByIdLocal = new Map<string, LayoutNode>();
 
     function addNode(id: string, kind: string, name: string, subtype: string, extra: Record<string, any> = {}): void {
         if (!id || nodeIds.has(id)) return;
         nodeIds.add(id);
-        nodes.push({ id, kind, name: name || id, subtype: subtype || '', tags: extra.tags || [], ...extra });
+        const node = { id, kind, name: name || id, subtype: subtype || '', tags: extra.tags || [], ...extra };
+        nodes.push(node);
+        nodeByIdLocal.set(id, node);
     }
 
-    function addEdge(from: string, to: string, field: string, label: string = ''): void {
+    function addEdge(from: string, to: string, field: string, label: string = '', slot?: { list: string; index: number; ref: string }): void {
-        if (!from || !to || !nodeIds.has(from) || !nodeIds.has(to)) return;
+        if (!from || !to) return;
+        // The referrer (`to`) is always a current entity in these loops; if the
+        // referenced entity (`from`) is missing, the reference is dangling —
+        // record it so the editor can surface a "broken reference" warning
+        // instead of silently dropping the edge (the old behaviour).
+        if (!nodeIds.has(from)) {
+            if (nodeIds.has(to)) brokenRefs.push({ ref: from, by: to, field });
+            return;
+        }
+        if (!nodeIds.has(to)) return;
         const type = edgeType(
-            nodes.find(n => n.id === from)?.kind ?? '',
+            nodeByIdLocal.get(from)?.kind ?? '',
-            nodes.find(n => n.id === to)?.kind ?? '',
+            nodeByIdLocal.get(to)?.kind ?? '',
             field
         );
         // Edges with dotted fields are nested (composite layers, zones, etc.) — not drag-editable
         const editable = !field.includes('.');
-        edges.push({ from, to, field, label, type, editable });
+        edges.push({ from, to, field, label, type, editable, ...(slot ? { slot } : {}) });
     }
 
+    // Every entity may carry a custom `icon` (+ `icon_color`); pass them through
+    // so node rendering can honour them (parity with custom node colours).
     // 1. Devices
     for (const d of e.devices || []) {
-        addNode(d.id, 'device', d.name, d.device_type, { tags: d.tags });
+        addNode(d.id, 'device', d.name, d.device_type, { tags: d.tags, icon: d.icon, iconColor: d.icon_color });
     }
 
     // 2. Capture templates
     for (const t of e.captureTemplates || []) {
-        addNode(t.id, 'capture_template', t.name, t.engine_type, { tags: t.tags });
+        addNode(t.id, 'capture_template', t.name, t.engine_type, { tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // 3. PP templates
     for (const t of e.ppTemplates || []) {
-        addNode(t.id, 'pp_template', t.name, '', { tags: t.tags });
+        addNode(t.id, 'pp_template', t.name, '', { tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // 4. Audio templates
     for (const t of e.audioTemplates || []) {
-        addNode(t.id, 'audio_template', t.name, t.engine_type, { tags: t.tags });
+        addNode(t.id, 'audio_template', t.name, t.engine_type, { tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // 5. Pattern templates
     for (const t of e.patternTemplates || []) {
-        addNode(t.id, 'pattern_template', t.name, '', { tags: t.tags });
+        addNode(t.id, 'pattern_template', t.name, '', { tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // 6. Sync clocks
     for (const c of e.syncClocks || []) {
-        addNode(c.id, 'sync_clock', c.name, '', { running: c.is_running !== false, tags: c.tags });
+        addNode(c.id, 'sync_clock', c.name, '', { running: c.is_running !== false, tags: c.tags, icon: c.icon, iconColor: c.icon_color });
     }
 
     // 7. Picture sources
     for (const s of e.pictureSources || []) {
-        addNode(s.id, 'picture_source', s.name, s.stream_type, { tags: s.tags });
+        addNode(s.id, 'picture_source', s.name, s.stream_type, { tags: s.tags, icon: s.icon, iconColor: s.icon_color });
     }
 
     // 8. Audio sources
     for (const s of e.audioSources || []) {
-        addNode(s.id, 'audio_source', s.name, s.source_type, { tags: s.tags });
+        addNode(s.id, 'audio_source', s.name, s.source_type, { tags: s.tags, icon: s.icon, iconColor: s.icon_color });
     }
 
     // 9. Value sources
     for (const s of e.valueSources || []) {
-        addNode(s.id, 'value_source', s.name, s.source_type, { tags: s.tags });
+        addNode(s.id, 'value_source', s.name, s.source_type, { tags: s.tags, icon: s.icon, iconColor: s.icon_color });
     }
 
     // 10. Color strip sources
     for (const s of e.colorStripSources || []) {
-        addNode(s.id, 'color_strip_source', s.name, s.source_type, { tags: s.tags });
+        addNode(s.id, 'color_strip_source', s.name, s.source_type, { tags: s.tags, icon: s.icon, iconColor: s.icon_color });
     }
 
     // 11. Output targets
     for (const t of e.outputTargets || []) {
-        addNode(t.id, 'output_target', t.name, t.target_type, { running: t.running || false, tags: t.tags });
+        addNode(t.id, 'output_target', t.name, t.target_type, { running: t.running || false, tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // 12. Scene presets
     for (const s of e.scenePresets || []) {
-        addNode(s.id, 'scene_preset', s.name, '', { tags: s.tags });
+        addNode(s.id, 'scene_preset', s.name, '', { tags: s.tags, icon: s.icon, iconColor: s.icon_color });
     }
 
     // 13. Automations
     for (const a of e.automations || []) {
-        addNode(a.id, 'automation', a.name, '', { running: a.enabled || false, tags: a.tags });
+        addNode(a.id, 'automation', a.name, '', { running: a.enabled || false, tags: a.tags, icon: a.icon, iconColor: a.icon_color });
     }
 
     // 14. Color strip processing templates (CSPT)
     for (const t of e.csptTemplates || []) {
-        addNode(t.id, 'cspt', t.name, '', { tags: t.tags });
+        addNode(t.id, 'cspt', t.name, '', { tags: t.tags, icon: t.icon, iconColor: t.icon_color });
     }
 
     // ── Edges ──
@@ -319,6 +352,21 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
     for (const s of e.valueSources || []) {
         if (s.audio_source_id) addEdge(s.audio_source_id, s.id, 'audio_source_id');
         if (s.picture_source_id) addEdge(s.picture_source_id, s.id, 'picture_source_id');
+        // Derived value sources: gradient_map derives from an inner value source;
+        // css_extract derives from a color strip. Both are real, runtime-resolved
+        // references (and drag-editable) — render them so they're visible.
+        if (s.value_source_id) addEdge(s.value_source_id, s.id, 'value_source_id');
+        if (s.color_strip_source_id) addEdge(s.color_strip_source_id, s.id, 'color_strip_source_id');
+        // Template value sources reference one inner value source per bound input.
+        // Each `inputs[].value_source_id` is a real 'value' edge; the dotted field
+        // path marks it non-editable (drag-wiring deferred — see graph-connections).
+        if (s.source_type === 'template' && Array.isArray(s.inputs)) {
+            s.inputs.forEach((inp: any) => {
+                if (inp?.value_source_id) {
+                    addEdge(inp.value_source_id, s.id, `inputs[${inp.name}].value_source_id`);
+                }
+            });
+        }
     }
 
     // Color strip source edges
@@ -331,19 +379,20 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         if (s.input_source_id) addEdge(s.input_source_id, s.id, 'input_source_id');
         if (s.processing_template_id) addEdge(s.processing_template_id, s.id, 'processing_template_id');
 
-        // Composite layers
+        // Composite layers — carry the slot index so each `layer.source_id`
+        // edge can be re-wired individually from the graph (siblings untouched).
         if (s.layers) {
-            for (const layer of s.layers) {
+            s.layers.forEach((layer: any, i: number) => {
-                if (layer.source_id) addEdge(layer.source_id, s.id, 'layer.source_id');
+                if (layer.source_id) addEdge(layer.source_id, s.id, 'layer.source_id', '', { list: 'layers', index: i, ref: 'source_id' });
                 if (layer.brightness_source_id) addEdge(layer.brightness_source_id, s.id, 'layer.brightness_source_id');
-            }
+            });
         }
 
-        // Mapped zones
+        // Mapped zones — carry the slot index (re-wirable from the graph).
         if (s.zones) {
-            for (const zone of s.zones) {
+            s.zones.forEach((zone: any, i: number) => {
-                if (zone.source_id) addEdge(zone.source_id, s.id, 'zone.source_id');
+                if (zone.source_id) addEdge(zone.source_id, s.id, 'zone.source_id', '', { list: 'zones', index: i, ref: 'source_id' });
-            }
+            });
         }
 
         // Advanced picture calibration lines
@@ -376,7 +425,6 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         if (bvsId) addEdge(bvsId, t.id, 'brightness.source_id');
         const transVsId = bindableSourceId(t.transition);
         if (transVsId) addEdge(transVsId, t.id, 'transition.source_id');
-        if (t.picture_source_id) addEdge(t.picture_source_id, t.id, 'picture_source_id');
         // KC target settings
         if (t.settings) {
             if (t.settings.pattern_template_id) addEdge(t.settings.pattern_template_id, t.id, 'settings.pattern_template_id');
@@ -414,7 +462,7 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         if (d.default_css_processing_template_id) addEdge(d.default_css_processing_template_id, d.id, 'default_css_processing_template_id');
     }
 
-    return { nodes, edges };
+    return { nodes, edges, brokenRefs };
 }
 
 /* ── Port computation ── */

server/src/ledgrab/static/js/core/graph-nodes.ts

@@ -6,6 +6,7 @@ import { ENTITY_COLORS, NODE_WIDTH, NODE_HEIGHT, computePorts } from './graph-la
 import { EDGE_COLORS } from './graph-edges.ts';
 import { createColorPicker, registerColorPicker, closeAllColorPickers } from './color-picker.ts';
 import { getCardColor, setCardColor } from './card-colors.ts';
+import { renderDeviceIconSvg } from './device-icons.ts';
 import * as P from './icon-paths.ts';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
@@ -22,6 +23,8 @@ interface GraphNode {
     kind: string;
     name: string;
     subtype?: string;
+    icon?: string;
+    iconColor?: string;
     x: number;
     y: number;
     width: number;
@@ -103,6 +106,7 @@ const SUBTYPE_ICONS = {
     value_source: {
         static: P.layoutDashboard, animated: P.refreshCw, audio: P.music,
         adaptive_time: P.clock, adaptive_scene: P.cloudSun, daylight: P.sun,
+        template: P.code,
     },
     audio_source: { capture: P.volume2, processed: P.slidersHorizontal },
     output_target: { led: P.lightbulb, wled: P.lightbulb, ha_light: P.lightbulb },
@@ -360,15 +364,29 @@ function renderNode(node: GraphNode, callbacks: NodeCallbacks): SVGElement {
         }
     }
 
-    // Entity icon (right side)
+    // Entity icon (right side). A custom per-entity icon wins over the
-    const iconPaths = (SUBTYPE_ICONS[kind]?.[subtype]) || KIND_ICONS[kind];
+    // kind/subtype default (parity with custom node colours); unknown icon ids
-    if (iconPaths) {
+    // yield '' so we fall back gracefully.
+    const customIconSvg = node.icon ? renderDeviceIconSvg(node.icon, { size: 16 }) : '';
+    if (customIconSvg) {
         const iconG = svgEl('g', {
-            class: 'graph-node-icon',
+            class: 'graph-node-custom-icon',
-            transform: `translate(${width - 28}, ${height / 2 - 8}) scale(0.667)`,
+            transform: `translate(${width - 28}, ${height / 2 - 8})`,
         });
-        iconG.innerHTML = iconPaths;
+        iconG.innerHTML = customIconSvg;
+        // The rendered SVG strokes with currentColor — tint via `color`.
+        if (node.iconColor) (iconG as unknown as SVGGElement).style.color = node.iconColor;
         g.appendChild(iconG);
+    } else {
+        const iconPaths = (SUBTYPE_ICONS[kind]?.[subtype]) || KIND_ICONS[kind];
+        if (iconPaths) {
+            const iconG = svgEl('g', {
+                class: 'graph-node-icon',
+                transform: `translate(${width - 28}, ${height / 2 - 8}) scale(0.667)`,
+            });
+            iconG.innerHTML = iconPaths;
+            g.appendChild(iconG);
+        }
     }
 
     // Running dot
@@ -627,6 +645,39 @@ export function markOrphans(group: SVGGElement, nodeMap: Map<string, GraphNode>,
     }
 }
 
+/**
+ * Mark nodes that have configuration issues (e.g. broken references, cycles).
+ * Adds a warning badge anchored to the node's top-left corner with a tooltip
+ * describing every problem. Call after `renderNodes`.
+ */
+export function markIssues(group: SVGGElement, issues: Map<string, string[]>): void {
+    // Clear previous markers so repeated calls don't stack badges.
+    group.querySelectorAll('.graph-node-issue').forEach(e => e.remove());
+    group.querySelectorAll('.graph-node.has-issue').forEach(n => n.classList.remove('has-issue'));
+
+    for (const [id, msgs] of issues) {
+        if (!msgs.length) continue;
+        const el = group.querySelector(`.graph-node[data-id="${CSS.escape(id)}"]`);
+        if (!el) continue;
+        el.classList.add('has-issue');
+
+        const badge = svgEl('g', { class: 'graph-node-issue' });
+        const icon = svgEl('g', { transform: 'translate(2, -9) scale(0.6)' });
+        icon.innerHTML = P.triangleAlert;
+        icon.setAttribute('fill', 'none');
+        icon.setAttribute('stroke', 'currentColor');
+        icon.setAttribute('stroke-width', '2.5');
+        icon.setAttribute('stroke-linecap', 'round');
+        icon.setAttribute('stroke-linejoin', 'round');
+        badge.appendChild(icon);
+
+        const tip = svgEl('title');
+        tip.textContent = msgs.join('\n');
+        badge.appendChild(tip);
+        el.appendChild(badge);
+    }
+}
+
 /**
  * Update selection state on nodes.
  */

server/src/ledgrab/static/js/core/icons.ts

@@ -43,6 +43,7 @@ const _valueSourceTypeIcons   = {
     system_metrics: _svg(P.cpu),
     game_event: _svg(P.gamepad2),
     http: _svg(P.globe),
+    template: _svg(P.code),
 };
 const _audioSourceTypeIcons   = { capture: _svg(P.volume2), processed: _svg(P.slidersHorizontal) };
 const _deviceTypeIcons        = {

server/src/ledgrab/static/js/core/jinja-editor.ts

@@ -0,0 +1,191 @@
+/**
+ * Tiny zero-dependency Jinja-expression highlighter.
+ *
+ * A transparent <textarea> is layered over a synced <pre class="jinja-hl">.
+ * On every input the text is re-tokenised and painted into the <pre> so the
+ * caret and selection stay native while the colours live underneath. The two
+ * layers share identical font metrics (set in CSS via --font-mono) so the
+ * highlight aligns pixel-perfectly with the typed glyphs.
+ *
+ * Tokenised: strings, numbers, the sandbox globals (min|max|abs|round|clamp),
+ * the `raw` keyword, bound input variable names (supplied live via
+ * getInputNames), and operators. Everything else renders as plain text.
+ *
+ * Usage:
+ *   const ed = create({ textarea, getInputNames: () => ['audio','temp'], onChange });
+ *   ed.refresh();   // re-paint after the input list or value changes externally
+ *   ed.destroy();
+ */
+
+/** Globals available inside the sandboxed expression (see backend contract). */
+const JINJA_GLOBALS = new Set(['min', 'max', 'abs', 'round', 'clamp']);
+const JINJA_RAW = 'raw';
+
+export interface JinjaEditorOpts {
+    textarea: HTMLTextAreaElement;
+    getInputNames: () => string[];
+    onChange?: (value: string) => void;
+}
+
+export interface JinjaEditorHandle {
+    /** Re-paint the highlight layer (e.g. after the bound-input list changed). */
+    refresh: () => void;
+    /** Detach listeners and remove the highlight overlay. */
+    destroy: () => void;
+}
+
+function escapeHtml(s: string): string {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+type TokenKind = 'str' | 'num' | 'fn' | 'raw' | 'var' | 'op' | 'text';
+
+interface Token {
+    kind: TokenKind;
+    text: string;
+}
+
+/**
+ * Tokenise a Jinja expression. Deliberately small — this is presentational
+ * only; the backend is the source of truth for validity.
+ */
+function tokenize(src: string, inputNames: Set<string>): Token[] {
+    const tokens: Token[] = [];
+    const n = src.length;
+    let i = 0;
+
+    const push = (kind: TokenKind, text: string) => {
+        // Coalesce consecutive plain-text runs to keep the DOM tiny.
+        const last = tokens[tokens.length - 1];
+        if (kind === 'text' && last && last.kind === 'text') last.text += text;
+        else tokens.push({ kind, text });
+    };
+
+    while (i < n) {
+        const ch = src[i];
+
+        // Strings — single or double quoted, with simple escape passthrough.
+        if (ch === '"' || ch === "'") {
+            const quote = ch;
+            let j = i + 1;
+            while (j < n && src[j] !== quote) {
+                if (src[j] === '\\' && j + 1 < n) j += 2;
+                else j += 1;
+            }
+            j = Math.min(j + 1, n); // include closing quote if present
+            push('str', src.slice(i, j));
+            i = j;
+            continue;
+        }
+
+        // Numbers — integer / float.
+        if (ch >= '0' && ch <= '9') {
+            let j = i + 1;
+            while (j < n && /[0-9._]/.test(src[j])) j += 1;
+            push('num', src.slice(i, j));
+            i = j;
+            continue;
+        }
+
+        // Identifiers — globals, the `raw` keyword, bound input names, or plain.
+        if (/[A-Za-z_]/.test(ch)) {
+            let j = i + 1;
+            while (j < n && /[A-Za-z0-9_]/.test(src[j])) j += 1;
+            const word = src.slice(i, j);
+            if (JINJA_GLOBALS.has(word)) push('fn', word);
+            else if (word === JINJA_RAW) push('raw', word);
+            else if (inputNames.has(word)) push('var', word);
+            else push('text', word);
+            i = j;
+            continue;
+        }
+
+        // Operators / punctuation.
+        if ('+-*/%()[]<>=!,&|?:'.includes(ch)) {
+            push('op', ch);
+            i += 1;
+            continue;
+        }
+
+        // Whitespace and everything else.
+        push('text', ch);
+        i += 1;
+    }
+
+    return tokens;
+}
+
+function render(src: string, inputNames: Set<string>): string {
+    // A trailing newline is swallowed by <pre>; pad it so the highlight box
+    // keeps the same height as the textarea while typing a fresh line.
+    const padded = src.endsWith('\n') ? src + ' ' : src;
+    const html = tokenize(padded, inputNames)
+        .map(tok =>
+            tok.kind === 'text'
+                ? escapeHtml(tok.text)
+                : `<span class="tok-${tok.kind}">${escapeHtml(tok.text)}</span>`,
+        )
+        .join('');
+    return html;
+}
+
+export function create({ textarea, getInputNames, onChange }: JinjaEditorOpts): JinjaEditorHandle {
+    // Wrap the textarea so the highlight layer can sit directly behind it.
+    const wrap = document.createElement('div');
+    wrap.className = 'jinja-editor';
+
+    const pre = document.createElement('pre');
+    pre.className = 'jinja-hl';
+    pre.setAttribute('aria-hidden', 'true');
+
+    const parent = textarea.parentNode;
+    if (parent) {
+        parent.insertBefore(wrap, textarea);
+        wrap.appendChild(pre);
+        wrap.appendChild(textarea);
+    }
+    textarea.classList.add('jinja-input');
+    textarea.spellcheck = false;
+    textarea.setAttribute('autocomplete', 'off');
+    textarea.setAttribute('autocapitalize', 'off');
+    textarea.setAttribute('autocorrect', 'off');
+    textarea.setAttribute('wrap', 'off');
+
+    const paint = () => {
+        pre.innerHTML = render(textarea.value, new Set(getInputNames()));
+        // Keep the highlight scrolled in lock-step with the textarea.
+        pre.scrollTop = textarea.scrollTop;
+        pre.scrollLeft = textarea.scrollLeft;
+    };
+
+    const onInput = () => {
+        paint();
+        if (onChange) onChange(textarea.value);
+    };
+    const onScroll = () => {
+        pre.scrollTop = textarea.scrollTop;
+        pre.scrollLeft = textarea.scrollLeft;
+    };
+
+    textarea.addEventListener('input', onInput);
+    textarea.addEventListener('scroll', onScroll);
+
+    paint();
+
+    return {
+        refresh: paint,
+        destroy: () => {
+            textarea.removeEventListener('input', onInput);
+            textarea.removeEventListener('scroll', onScroll);
+            textarea.classList.remove('jinja-input');
+            // Restore the textarea to its original place, drop the overlay.
+            if (wrap.parentNode) {
+                wrap.parentNode.insertBefore(textarea, wrap);
+                wrap.remove();
+            }
+        },
+    };
+}

server/src/ledgrab/static/js/core/process-picker.ts

@@ -2,13 +2,19 @@
  * Command-palette style name picker — reusable UI for browsing a list of
  * names fetched from any API endpoint.  Mirrors the EntityPalette pattern.
  *
- * Two concrete pickers are exported:
+ * Three concrete pickers are exported:
  *
  *   - **ProcessPalette** — picks from running OS processes (`/system/processes`)
  *   - **NotificationAppPalette** — picks from OS notification history apps
+ *   - **AppPalette** — picks from Android launchable apps (`/system/installed-apps`),
+ *     displaying the human label but inserting the package name
  *
- * Both support single-select (returns one value) and multi-select (appends to
+ * Items may be plain strings (display == stored value) or `{ value, label }`
- * a textarea).
+ * pairs (display the label, store the value — used by AppPalette so the rule
+ * stores the package name while the user sees "Netflix").
+ *
+ * All support single-select (returns one value) and multi-select (appends the
+ * value to a textarea).
  *
  * Usage:
  *
@@ -29,8 +35,16 @@ import { ICON_SEARCH } from './icons.ts';
 
 /* ─── types ────────────────────────────────────────────────── */
 
-interface PaletteItem {
+/** An item with a display label distinct from its stored value. */
-    name: string;
+interface AppItem {
+    value: string;
+    label: string;
+}
+
+/** Raw items a fetcher may return: bare strings or labelled pairs. */
+type RawItem = string | AppItem;
+
+interface PaletteEntry extends AppItem {
     added: boolean;
 }
 
@@ -44,7 +58,9 @@ interface PickMultiOpts {
     placeholder?: string;
 }
 
-type FetchItemsFn = () => Promise<string[]>;
+type FetchItemsFn = () => Promise<RawItem[]>;
+
+const DEFAULT_EMPTY_KEY = 'automations.condition.application.no_processes';
 
 /* ─── generic NamePalette (shared logic) ───────────────────── */
 
@@ -53,19 +69,21 @@ class NamePalette {
     private _input: HTMLInputElement;
     private _list: HTMLDivElement;
     private _fetchItems: FetchItemsFn;
+    private _emptyKey: string;
 
     private _resolveSingle: ((v: string | undefined) => void) | null = null;
     private _multiTextarea: HTMLTextAreaElement | null = null;
 
-    private _items: string[] = [];
+    private _items: AppItem[] = [];
     private _existing: Set<string> = new Set();
-    private _filtered: PaletteItem[] = [];
+    private _filtered: PaletteEntry[] = [];
     private _highlightIdx = 0;
     private _currentValue: string | undefined;
     private _isMulti = false;
 
-    constructor(fetchItems: FetchItemsFn) {
+    constructor(fetchItems: FetchItemsFn, emptyKey: string = DEFAULT_EMPTY_KEY) {
         this._fetchItems = fetchItems;
+        this._emptyKey = emptyKey;
 
         this._overlay = document.createElement('div');
         this._overlay.className = 'entity-palette-overlay process-palette-overlay';
@@ -107,14 +125,20 @@ class NamePalette {
             this._isMulti = true;
             this._multiTextarea = opts.textarea;
             this._resolveSingle = resolve as any;
-            this._existing = new Set(
+            this._existing = this._textareaValues(opts.textarea);
-                opts.textarea.value.split('\n').map(s => s.trim().toLowerCase()).filter(Boolean),
-            );
             this._currentValue = undefined;
             this._open(opts.placeholder);
         });
     }
 
+    private _textareaValues(ta: HTMLTextAreaElement): Set<string> {
+        return new Set(ta.value.split('\n').map(s => s.trim().toLowerCase()).filter(Boolean));
+    }
+
+    private _normalize(raw: RawItem[]): AppItem[] {
+        return raw.map(r => (typeof r === 'string' ? { value: r, label: r } : r));
+    }
+
     private async _open(placeholder?: string) {
         this._input.placeholder = placeholder || '';
         this._input.value = '';
@@ -123,15 +147,13 @@ class NamePalette {
         requestAnimationFrame(() => this._input.focus());
 
         try {
-            this._items = await this._fetchItems();
+            this._items = this._normalize(await this._fetchItems());
         } catch {
             this._items = [];
         }
 
         if (this._isMulti) {
-            this._existing = new Set(
+            this._existing = this._textareaValues(this._multiTextarea!);
-                this._multiTextarea!.value.split('\n').map(s => s.trim().toLowerCase()).filter(Boolean),
-            );
         }
 
         this._filter();
@@ -142,14 +164,11 @@ class NamePalette {
     private _filter() {
         const q = this._input.value.toLowerCase().trim();
         this._filtered = this._items
-            .filter(p => !q || p.toLowerCase().includes(q))
+            .filter(p => !q || p.label.toLowerCase().includes(q) || p.value.toLowerCase().includes(q))
-            .map(p => ({
+            .map(p => ({ ...p, added: this._existing.has(p.value.toLowerCase()) }));
-                name: p,
-                added: this._existing.has(p.toLowerCase()),
-            }));
 
         this._highlightIdx = this._filtered.findIndex(
-            i => i.name.toLowerCase() === (this._currentValue || '').toLowerCase(),
+            i => i.value.toLowerCase() === (this._currentValue || '').toLowerCase(),
         );
         if (this._highlightIdx === -1) this._highlightIdx = 0;
         this._render();
@@ -158,9 +177,7 @@ class NamePalette {
     private _render() {
         if (this._filtered.length === 0) {
             this._list.innerHTML = `<div class="entity-palette-empty">${
-                this._items.length === 0
+                this._items.length === 0 ? t(this._emptyKey) : '—'
-                    ? t('automations.condition.application.no_processes')
-                    : '—'
             }</div>`;
             return;
         }
@@ -170,12 +187,21 @@ class NamePalette {
                 'entity-palette-item',
                 i === this._highlightIdx ? 'ep-highlight' : '',
                 item.added ? 'ep-current' : '',
-                item.name.toLowerCase() === (this._currentValue || '').toLowerCase() ? 'ep-current' : '',
+                item.value.toLowerCase() === (this._currentValue || '').toLowerCase() ? 'ep-current' : '',
             ].filter(Boolean).join(' ');
 
+            // When the label differs from the stored value (e.g. "Netflix" vs
+            // "com.netflix.mediaclient"), show the value as a secondary line so
+            // users can see exactly what gets matched. Otherwise fall back to the
+            // ✓ added-marker.
+            const showValue = item.label !== item.value;
+            const trailing = showValue
+                ? `<span class="ep-item-desc">${escapeHtml(item.value)}</span>`
+                : (item.added ? '<span class="ep-item-desc">✓</span>' : '');
+
             return `<div class="${cls}" data-idx="${i}">
-                <span class="ep-item-label">${escapeHtml(item.name)}</span>
+                <span class="ep-item-label">${escapeHtml(item.label)}</span>
-                ${item.added ? '<span class="ep-item-desc">\u2713</span>' : ''}
+                ${trailing}
             </div>`;
         }).join('');
 
@@ -192,19 +218,19 @@ class NamePalette {
 
     /* ── selection ──────────────────────────────────────────── */
 
-    private _selectItem(item: PaletteItem) {
+    private _selectItem(item: PaletteEntry) {
         if (this._isMulti) {
             if (!item.added) {
                 const ta = this._multiTextarea!;
                 const cur = ta.value.trim();
-                ta.value = cur ? cur + '\n' + item.name : item.name;
+                ta.value = cur ? cur + '\n' + item.value : item.value;
-                this._existing.add(item.name.toLowerCase());
+                this._existing.add(item.value.toLowerCase());
                 item.added = true;
                 this._render();
             }
         } else {
             this._overlay.classList.remove('open');
-            if (this._resolveSingle) this._resolveSingle(item.name);
+            if (this._resolveSingle) this._resolveSingle(item.value);
             this._resolveSingle = null;
         }
     }
@@ -269,6 +295,17 @@ async function _fetchNotificationApps(): Promise<string[]> {
     return Array.from(seen.values()).sort((a, b) => a.localeCompare(b));
 }
 
+async function _fetchInstalledApps(): Promise<AppItem[]> {
+    try {
+        const data = await apiGet<{ apps?: Array<{ package: string; label: string }> }>(
+            '/system/installed-apps',
+        );
+        return (data.apps || []).map(a => ({ value: a.package, label: a.label || a.package }));
+    } catch {
+        return [];
+    }
+}
+
 /* ─── ProcessPalette (running processes) ───────────────────── */
 
 let _processInst: NamePalette | null = null;
@@ -301,6 +338,22 @@ export class NotificationAppPalette {
     }
 }
 
+/* ─── AppPalette (Android launchable apps) ─────────────────── */
+
+let _appInst: NamePalette | null = null;
+
+export class AppPalette {
+    static pick(opts: PickOpts): Promise<string | undefined> {
+        if (!_appInst) _appInst = new NamePalette(_fetchInstalledApps, 'automations.rule.application.no_apps');
+        return _appInst.pickSingle(opts);
+    }
+
+    static pickMulti(opts: PickMultiOpts): Promise<void> {
+        if (!_appInst) _appInst = new NamePalette(_fetchInstalledApps, 'automations.rule.application.no_apps');
+        return _appInst.pickMulti(opts);
+    }
+}
+
 /* ─── drop-in replacement for the old attachProcessPicker ─── */
 
 /**
@@ -334,3 +387,19 @@ export function attachNotificationAppPicker(containerEl: HTMLElement, textareaEl
         });
     });
 }
+
+/**
+ * Wire up a `.btn-browse-apps` button to open the Android launchable-app palette
+ * (multi-select, feeding package names into a textarea while showing labels).
+ */
+export function attachAppPicker(containerEl: HTMLElement, textareaEl: HTMLTextAreaElement): void {
+    const browseBtn = containerEl.querySelector('.btn-browse-apps');
+    if (!browseBtn) return;
+
+    browseBtn.addEventListener('click', () => {
+        AppPalette.pickMulti({
+            textarea: textareaEl,
+            placeholder: t('automations.rule.application.search_apps') || 'Filter apps…',
+        });
+    });
+}

server/src/ledgrab/static/js/features/automations.ts

@@ -29,7 +29,7 @@ import { getBaseOrigin } from './settings.ts';
 import { IconSelect } from '../core/icon-select.ts';
 import { EntitySelect } from '../core/entity-palette.ts';
 import { enhanceMiniSelects } from '../core/mini-select.ts';
-import { attachProcessPicker } from '../core/process-picker.ts';
+import { attachProcessPicker, attachAppPicker } from '../core/process-picker.ts';
 import { TreeNav } from '../core/tree-nav.ts';
 import { csScenes, createSceneCard, initScenePresetDelegation } from './scene-presets.ts';
 import type { Automation, RuleType } from '../types.ts';
@@ -215,6 +215,28 @@ document.addEventListener('server:automation_state_changed', () => {
     if (apiKey && isActiveTab('automations')) loadAutomations();
 });
 
+/** Platform capability signal from `/system/info` — drives the application-rule
+ *  editor (process picker + match types on desktop vs. app picker + foreground-only
+ *  on Android) and the Usage-Access banner. Fetched once and cached. */
+interface PlatformInfo {
+    is_android: boolean;
+    app_match_kind: 'process' | 'package';
+    usage_access_granted: boolean;
+}
+
+let _platformInfo: PlatformInfo | null = null;
+
+async function ensurePlatformInfo(): Promise<PlatformInfo> {
+    if (_platformInfo) return _platformInfo;
+    try {
+        _platformInfo = await apiGet<PlatformInfo>('/system/info');
+    } catch {
+        // Default to desktop semantics if the signal can't be fetched.
+        _platformInfo = { is_android: false, app_match_kind: 'process', usage_access_granted: true };
+    }
+    return _platformInfo;
+}
+
 export async function loadAutomations() {
     if (_automationsLoading) return;
     set_automationsLoading(true);
@@ -222,6 +244,10 @@ export async function loadAutomations() {
     if (!container) { set_automationsLoading(false); return; }
     if (!csAutomations.isMounted()) setTabRefreshing('automations-content', true);
 
+    // Prime the platform signal so the editor renders the right app source +
+    // match semantics without an async hop when a rule row is expanded.
+    void ensurePlatformInfo();
+
     try {
         const [automations, scenes] = await Promise.all([
             automationsCacheObj.fetch(),
@@ -559,6 +585,11 @@ export async function openAutomationEditor(automationId?: any, cloneData?: any)
     errorEl.style.display = 'none';
     ruleList!.innerHTML = '';
 
+    // Ensure the platform signal is loaded before rendering rule rows so the
+    // application rule picks the right app source + match semantics. The
+    // automations tab primes this, but the graph editor opens this directly.
+    await ensurePlatformInfo();
+
     _ensureRuleLogicIconSelect();
     _ensureDeactivationModeIconSelect();
 
@@ -1129,6 +1160,33 @@ function _renderWebhookFields(container: HTMLElement, data: any): void {
 
 function _renderApplicationFields(container: HTMLElement, data: any): void {
     const appsValue = (data.apps || []).join('\n');
+
+    // On Android there is exactly one obtainable signal — the foreground app —
+    // so the match-type selector is hidden (match_type is forced to "topmost" by
+    // the collector) and the app list comes from launchable apps (package names)
+    // rather than running processes (process names).
+    if (_platformInfo?.is_android) {
+        const banner = _platformInfo.usage_access_granted
+            ? ''
+            : `<div class="rule-usage-warning">${t('automations.rule.application.usage_access_required')}</div>`;
+        container.innerHTML = `
+            <div class="rule-fields">
+                ${banner}
+                <div class="rule-field">
+                    <div class="rule-apps-header">
+                        <label>${t('automations.rule.application.apps')}</label>
+                        <button type="button" class="btn btn-icon btn-secondary btn-browse-apps" title="${t('automations.rule.application.browse')}">${ICON_SEARCH}</button>
+                    </div>
+                    <textarea class="rule-apps" rows="3" placeholder="com.netflix.mediaclient&#10;com.android.chrome">${escapeHtml(appsValue)}</textarea>
+                    <small class="rule-hint-desc">${t('automations.rule.application.apps.hint_android')}</small>
+                </div>
+            </div>
+        `;
+        const textarea = container.querySelector('.rule-apps') as HTMLTextAreaElement;
+        attachAppPicker(container, textarea);
+        return;
+    }
+
     const matchType = data.match_type || 'running';
     container.innerHTML = `
         <div class="rule-fields">
@@ -1299,7 +1357,10 @@ const RULE_COLLECTORS: Record<RuleType, RuleCollector> = {
         return r;
     },
     application: (row) => {
-        const matchType = (row.querySelector('.rule-match-type') as HTMLSelectElement).value;
+        // On Android the match-type selector is hidden (only the foreground app is
+        // detectable), so default to "topmost" when the select isn't present.
+        const matchSel = row.querySelector('.rule-match-type') as HTMLSelectElement | null;
+        const matchType = matchSel ? matchSel.value : 'topmost';
         const appsText = (row.querySelector('.rule-apps') as HTMLTextAreaElement).value.trim();
         const apps = appsText ? appsText.split('\n').map(a => a.trim()).filter(Boolean) : [];
         return { rule_type: 'application', apps, match_type: matchType };

server/src/ledgrab/static/js/features/color-strips/index.ts

@@ -180,6 +180,8 @@ class CSSEditorModal extends Modal {
             notification_default_color: getNotificationDefaultColorSnapshot(),
             notification_filter_mode: (document.getElementById('css-editor-notification-filter-mode') as HTMLInputElement).value,
             notification_filter_list: (document.getElementById('css-editor-notification-filter-list') as HTMLInputElement).value,
+            notification_sound: (document.getElementById('css-editor-notification-sound') as HTMLSelectElement).value,
+            notification_volume: getNotificationVolumeSnapshot(),
             notification_app_overrides: JSON.stringify(notificationGetRawAppOverrides()),
             clock_id: (document.getElementById('css-editor-clock') as HTMLInputElement).value,
             daylight_speed: (document.getElementById('css-editor-daylight-speed') as HTMLInputElement).value,

server/src/ledgrab/static/js/features/color-strips/notification.ts

@@ -233,15 +233,14 @@ function _overridesRenderList() {
 
     // Wire EntitySelects for sound dropdowns
     list.querySelectorAll<HTMLSelectElement>('.notif-override-sound').forEach(sel => {
-        const items = _getSoundAssetItems();
+        const es = new EntitySelect({
-        if (items.length > 0) {
+            target: sel,
-            const es = new EntitySelect({
+            getItems: () => _getSoundAssetItems(),
-                target: sel,
+            placeholder: t('color_strip.notification.sound.search') || 'Search sounds…',
-                getItems: () => _getSoundAssetItems(),
+            allowNone: true,
-                placeholder: t('color_strip.notification.sound.search') || 'Search sounds…',
+            noneLabel: t('color_strip.notification.sound.none'),
-            });
+        });
-            _overrideEntitySelects.push(es);
+        _overrideEntitySelects.push(es);
-        }
     });
 }
 
@@ -300,14 +299,13 @@ export function ensureNotifSoundEntitySelect() {
     if (!sel) return;
     _populateSoundOptions(sel);
     if (_notifSoundEntitySelect) _notifSoundEntitySelect.destroy();
-    const items = _getSoundAssetItems();
+    _notifSoundEntitySelect = new EntitySelect({
-    if (items.length > 0) {
+        target: sel,
-        _notifSoundEntitySelect = new EntitySelect({
+        getItems: () => _getSoundAssetItems(),
-            target: sel,
+        placeholder: t('color_strip.notification.sound.search') || 'Search sounds…',
-            getItems: () => _getSoundAssetItems(),
+        allowNone: true,
-            placeholder: t('color_strip.notification.sound.search') || 'Search sounds…',
+        noneLabel: t('color_strip.notification.sound.none'),
-        });
+    });
-    }
 }
 
 /* ── Test notification ────────────────────────────────────────── */

server/src/ledgrab/static/js/features/device-discovery.ts

@@ -5,7 +5,7 @@
 import {
     _discoveryScanRunning, set_discoveryScanRunning,
     _discoveryCache, set_discoveryCache,
-    csptCache,
+    csptCache, mqttSourcesCache,
 } from '../core/state.ts';
 import { API_BASE, isSerialDevice, isMockDevice, isMqttDevice, isWsDevice, isOpenrgbDevice, isDmxDevice, isDdpDevice, isOpcDevice, isEspnowDevice, isHueDevice, isYeelightDevice, isWizDevice, isLifxDevice, isGoveeDevice, isNanoleafDevice, isBleDevice, isUsbhidDevice, isSpiDevice, isChromaDevice, isGameSenseDevice, isGroupDevice, escapeHtml } from '../core/api.ts';
 import { apiGet, apiPost } from '../core/api-client.ts';
@@ -18,6 +18,7 @@ import { runPairingFlow, PairingCancelled } from './pairing-flow.ts';
 import { getDeviceTypeIcon, ICON_RADIO, ICON_GLOBE, ICON_CPU, ICON_KEYBOARD, ICON_MOUSE, ICON_HEADPHONES, ICON_PLUG, ICON_TARGET_ICON, ICON_ACTIVITY, ICON_TEMPLATE, ICON_CHEVRON_UP, ICON_CHEVRON_DOWN, ICON_PLUS, ICON_TRASH, ICON_GIT_MERGE, ICON_COPY, ICON_BLUETOOTH, ICON_LIGHTBULB, ICON_SPARKLES, ICON_PALETTE } from '../core/icons.ts';
 import { EntitySelect, EntityPalette } from '../core/entity-palette.ts';
 import { IconSelect, showTypePicker } from '../core/icon-select.ts';
+import type { MQTTSource } from '../types.ts';
 
 class AddDeviceModal extends Modal {
     constructor() { super('add-device-modal'); }
@@ -44,6 +45,7 @@ class AddDeviceModal extends Modal {
             opcChannel: (document.getElementById('device-opc-channel') as HTMLInputElement)?.value || '0',
             bleFamily: (document.getElementById('device-ble-family') as HTMLSelectElement)?.value || '',
             bleGoveeKey: (document.getElementById('device-ble-govee-key') as HTMLInputElement)?.value || '',
+            mqttSource: (document.getElementById('device-mqtt-source') as HTMLSelectElement)?.value || '',
             yeelightMinInterval: (document.getElementById('device-yeelight-min-interval') as HTMLInputElement)?.value || '500',
             wizMinInterval: (document.getElementById('device-wiz-min-interval') as HTMLInputElement)?.value || '50',
             lifxMinInterval: (document.getElementById('device-lifx-min-interval') as HTMLInputElement)?.value || '50',
@@ -72,6 +74,7 @@ function _buildDeviceTypeItems() {
 
 let _deviceTypeIconSelect: any = null;
 let _csptEntitySelect: any = null;
+let _mqttSourceEntitySelect: any = null;
 
 function _ensureDeviceTypeIconSelect() {
     const sel = document.getElementById('device-type');
@@ -104,6 +107,36 @@ function _ensureCsptEntitySelect() {
     }
 }
 
+// MQTT broker picker for device_type=mqtt. Empty value = first available broker.
+function _ensureMqttSourceSelect() {
+    const sel = document.getElementById('device-mqtt-source') as HTMLSelectElement | null;
+    if (!sel) return;
+    const sources: MQTTSource[] = mqttSourcesCache.data || [];
+    const current = sel.value;
+    sel.innerHTML = `<option value="">${t('device.mqtt_source.none')}</option>` +
+        sources.map((s: MQTTSource) => `<option value="${escapeHtml(s.id)}">${escapeHtml(s.name)}</option>`).join('');
+    sel.value = current;
+    if (_mqttSourceEntitySelect) _mqttSourceEntitySelect.destroy();
+    _mqttSourceEntitySelect = new EntitySelect({
+        target: sel,
+        getItems: () => (mqttSourcesCache.data || []).map((s: MQTTSource) => ({
+            value: s.id,
+            label: s.name,
+            icon: ICON_PALETTE,
+            desc: `${s.broker_host}:${s.broker_port}`,
+        })),
+        placeholder: t('palette.search'),
+        allowNone: true,
+        noneLabel: t('device.mqtt_source.none'),
+    } as any);
+}
+
+function _showMqttSourceField(show: boolean) {
+    const group = document.getElementById('device-mqtt-source-group') as HTMLElement | null;
+    if (group) group.style.display = show ? '' : 'none';
+    if (show) mqttSourcesCache.fetch().then(() => _ensureMqttSourceSelect());
+}
+
 /* ── Icon-grid DMX protocol selector ─────────────────────────── */
 
 function _buildDmxProtocolItems() {
@@ -297,6 +330,7 @@ export function onDeviceTypeChanged() {
     _showGameSenseFields(false);
     _showGroupFields(false);
     _showOpcFields(false);
+    _showMqttSourceField(false);
 
     if (isMqttDevice(deviceType)) {
         // MQTT: show URL (topic), LED count; hide serial/baud/led-type/latency/discovery
@@ -314,6 +348,7 @@ export function onDeviceTypeChanged() {
         if (urlLabel) urlLabel.textContent = t('device.mqtt_topic');
         if (urlHint) urlHint.textContent = t('device.mqtt_topic.hint');
         urlInput.placeholder = t('device.mqtt_topic.placeholder') || 'mqtt://ledgrab/device/living-room';
+        _showMqttSourceField(true);
     } else if (isMockDevice(deviceType)) {
         urlGroup.style.display = 'none';
         urlInput.removeAttribute('required');
@@ -920,6 +955,14 @@ export function showAddDevice(presetType: any = null, cloneData: any = null) {
             if (goveeKeyEl && cloneData.ble_govee_key) goveeKeyEl.value = cloneData.ble_govee_key;
             _updateBleGoveeKeyVisibility();
         }
+        // Prefill MQTT broker (after the source cache loads)
+        if (isMqttDevice(presetType) && cloneData.mqtt_source_id) {
+            mqttSourcesCache.fetch().then(() => {
+                const msEl = document.getElementById('device-mqtt-source') as HTMLSelectElement;
+                if (msEl) msEl.value = cloneData.mqtt_source_id;
+                _ensureMqttSourceSelect();
+            });
+        }
         // Prefill DMX fields
         if (isDmxDevice(presetType)) {
             const dmxProto = document.getElementById('device-dmx-protocol') as HTMLSelectElement;
@@ -1217,6 +1260,10 @@ export async function handleAddDevice(event: any) {
             const goveeKey = (document.getElementById('device-ble-govee-key') as HTMLInputElement)?.value?.trim();
             if (goveeKey) body.ble_govee_key = goveeKey;
         }
+        if (isMqttDevice(deviceType)) {
+            const mqttSource = (document.getElementById('device-mqtt-source') as HTMLSelectElement)?.value || '';
+            if (mqttSource) body.mqtt_source_id = mqttSource;
+        }
         if (isSpiDevice(deviceType)) {
             body.spi_speed_hz = parseInt((document.getElementById('device-spi-speed') as HTMLInputElement)?.value || '800000', 10);
             body.spi_led_type = (document.getElementById('device-spi-led-type') as HTMLSelectElement)?.value || 'WS2812B';

server/src/ledgrab/static/js/features/devices.ts

@@ -4,7 +4,7 @@
 
 import {
     _deviceBrightnessCache, updateDeviceBrightness,
-    csptCache,
+    csptCache, mqttSourcesCache,
 } from '../core/state.ts';
 import { API_BASE, getHeaders, escapeHtml, isSerialDevice, isMockDevice, isMqttDevice, isWsDevice, isOpenrgbDevice, isDmxDevice, isDdpDevice, isOpcDevice, isYeelightDevice, isWizDevice, isLifxDevice, isGoveeDevice, isNanoleafDevice, isBleDevice, isGroupDevice } from '../core/api.ts';
 import { apiGet, apiPost, apiPut, apiDelete } from '../core/api-client.ts';
@@ -13,18 +13,19 @@ import { _fetchOpenrgbZones, _getCheckedZones, _splitOpenrgbZone, _getZoneMode,
 import { t } from '../core/i18n.ts';
 import { showToast, showConfirm, desktopFocus } from '../core/ui.ts';
 import { Modal } from '../core/modal.ts';
-import { ICON_SETTINGS, ICON_STOP_PLAIN, ICON_LED, ICON_WEB, ICON_REFRESH, ICON_TEMPLATE } from '../core/icons.ts';
+import { ICON_SETTINGS, ICON_STOP_PLAIN, ICON_LED, ICON_WEB, ICON_REFRESH, ICON_TEMPLATE, ICON_PALETTE } from '../core/icons.ts';
 import { wrapCard } from '../core/card-colors.ts';
 import type { ModCardOpts, LedState, ModMetricOpts, ModChipOpts, ModBtnOpts, ModMenuItemOpts } from '../core/mod-card.ts';
 import { TagInput, renderTagChips } from '../core/tag-input.ts';
 import { EntitySelect } from '../core/entity-palette.ts';
 import { getBaseOrigin } from './settings.ts';
-import type { Device } from '../types.ts';
+import type { Device, MQTTSource } from '../types.ts';
 import { renderDeviceIconSvg } from '../core/device-icons.ts';
 import { ICON_EDIT } from '../core/icons.ts';
 
 let _deviceTagsInput: any = null;
 let _settingsCsptEntitySelect: any = null;
+let _settingsMqttEntitySelect: any = null;
 
 /* The General Settings modal groups its many conditional fields into
    four `.ds-section` panels (Identity / Connection / Hardware / Behavior).
@@ -73,6 +74,29 @@ function _ensureSettingsCsptSelect() {
     }
 }
 
+// MQTT broker picker for the settings modal (device_type=mqtt). Empty = first available.
+function _ensureSettingsMqttSelect(selectedId: string = '') {
+    const sel = document.getElementById('settings-mqtt-source') as HTMLSelectElement | null;
+    if (!sel) return;
+    const sources: MQTTSource[] = mqttSourcesCache.data || [];
+    sel.innerHTML = `<option value="">${t('device.mqtt_source.none')}</option>` +
+        sources.map((s: MQTTSource) => `<option value="${escapeHtml(s.id)}">${escapeHtml(s.name)}</option>`).join('');
+    sel.value = selectedId || '';
+    if (_settingsMqttEntitySelect) _settingsMqttEntitySelect.destroy();
+    _settingsMqttEntitySelect = new EntitySelect({
+        target: sel,
+        getItems: () => (mqttSourcesCache.data || []).map((s: MQTTSource) => ({
+            value: s.id,
+            label: s.name,
+            icon: ICON_PALETTE,
+            desc: `${s.broker_host}:${s.broker_port}`,
+        })),
+        placeholder: t('palette.search'),
+        allowNone: true,
+        noneLabel: t('device.mqtt_source.none'),
+    } as any);
+}
+
 class DeviceSettingsModal extends Modal {
     constructor() { super('device-settings-modal'); }
 
@@ -103,6 +127,7 @@ class DeviceSettingsModal extends Modal {
             goveeMinInterval: (document.getElementById('settings-govee-min-interval') as HTMLInputElement | null)?.value || '50',
             nanoleafMinInterval: (document.getElementById('settings-nanoleaf-min-interval') as HTMLInputElement | null)?.value || '100',
             csptId: (document.getElementById('settings-css-processing-template') as HTMLSelectElement | null)?.value || '',
+            mqttSource: (document.getElementById('settings-mqtt-source') as HTMLSelectElement | null)?.value || '',
         };
     }
 
@@ -439,6 +464,8 @@ export async function showSettings(deviceId: any) {
         const urlLabel = urlGroup.querySelector('label[for="settings-device-url"]') as HTMLElement | null;
         const urlHint = urlGroup.querySelector('.input-hint') as HTMLElement | null;
         const urlInput = document.getElementById('settings-device-url') as HTMLInputElement;
+        const mqttSourceGroup = document.getElementById('settings-mqtt-source-group') as HTMLElement | null;
+        if (mqttSourceGroup) mqttSourceGroup.style.display = 'none';
         if (isMock || isWs || isGroup) {
             urlGroup.style.display = 'none';
             urlInput.removeAttribute('required');
@@ -458,6 +485,7 @@ export async function showSettings(deviceId: any) {
                 if (urlLabel) urlLabel.textContent = t('device.mqtt_topic');
                 if (urlHint) urlHint.textContent = t('device.mqtt_topic.hint');
                 urlInput.placeholder = t('device.mqtt_topic.placeholder') || 'mqtt://ledgrab/device/living-room';
+                if (mqttSourceGroup) mqttSourceGroup.style.display = '';
             } else if (isOpenrgbDevice(device.device_type)) {
                 if (urlLabel) urlLabel.textContent = t('device.openrgb.url');
                 if (urlHint) urlHint.textContent = t('device.openrgb.url.hint');
@@ -805,6 +833,13 @@ export async function showSettings(deviceId: any) {
         const csptSel = document.getElementById('settings-css-processing-template') as HTMLSelectElement | null;
         if (csptSel) csptSel.value = device.default_css_processing_template_id || '';
 
+        // MQTT broker selector (mqtt devices only) — populated before snapshot
+        // so the dirty-check baseline matches the current broker.
+        if (isMqtt) {
+            await mqttSourcesCache.fetch();
+            _ensureSettingsMqttSelect(device.mqtt_source_id || '');
+        }
+
         _updateSettingsSectionVisibility();
         settingsModal.snapshot();
         settingsModal.open();
@@ -819,7 +854,7 @@ export async function showSettings(deviceId: any) {
 }
 
 export function isSettingsDirty() { return settingsModal.isDirty(); }
-export function forceCloseDeviceSettingsModal() { if (_deviceTagsInput) { _deviceTagsInput.destroy(); _deviceTagsInput = null; } if (_settingsCsptEntitySelect) { _settingsCsptEntitySelect.destroy(); _settingsCsptEntitySelect = null; } destroyBleFamilyIconSelect('settings-ble-family'); destroyDdpColorOrderIconSelect('settings-ddp-color-order'); destroyDmxProtocolIconSelect('settings-dmx-protocol'); settingsModal.forceClose(); }
+export function forceCloseDeviceSettingsModal() { if (_deviceTagsInput) { _deviceTagsInput.destroy(); _deviceTagsInput = null; } if (_settingsCsptEntitySelect) { _settingsCsptEntitySelect.destroy(); _settingsCsptEntitySelect = null; } if (_settingsMqttEntitySelect) { _settingsMqttEntitySelect.destroy(); _settingsMqttEntitySelect = null; } destroyBleFamilyIconSelect('settings-ble-family'); destroyDdpColorOrderIconSelect('settings-ddp-color-order'); destroyDmxProtocolIconSelect('settings-dmx-protocol'); settingsModal.forceClose(); }
 export function closeDeviceSettingsModal() { settingsModal.close(); }
 
 export async function saveDeviceSettings() {
@@ -908,6 +943,9 @@ export async function saveDeviceSettings() {
             const goveeKey = (document.getElementById('settings-ble-govee-key') as HTMLInputElement | null)?.value?.trim() || '';
             body.ble_govee_key = goveeKey;
         }
+        if (isMqttDevice(settingsModal.deviceType)) {
+            body.mqtt_source_id = (document.getElementById('settings-mqtt-source') as HTMLSelectElement | null)?.value || '';
+        }
         if (isGroup) {
             const childRows = document.querySelectorAll('#settings-group-children-list .group-child-row') as NodeListOf<HTMLElement>;
             body.group_device_ids = Array.from(childRows).map(r => r.dataset.deviceId || '').filter(v => v !== '');

server/src/ledgrab/static/js/features/graph-editor.ts

@@ -4,7 +4,8 @@
 
 import { GraphCanvas } from '../core/graph-canvas.ts';
 import { computeLayout, computePorts, ENTITY_COLORS, ENTITY_LABELS } from '../core/graph-layout.ts';
-import { renderNodes, patchNodeRunning, highlightNode, markOrphans, updateSelection, getNodeDisplayColor } from '../core/graph-nodes.ts';
+import type { BrokenRef } from '../core/graph-layout.ts';
+import { renderNodes, patchNodeRunning, highlightNode, markOrphans, markIssues, updateSelection, getNodeDisplayColor } from '../core/graph-nodes.ts';
 import { renderEdges, highlightChain, clearEdgeHighlights, updateEdgesForNode, renderFlowDots, updateFlowDotsForNode } from '../core/graph-edges.ts';
 import {
     devicesCache, captureTemplatesCache, ppTemplatesCache,
@@ -14,13 +15,14 @@ import {
     automationsCacheObj, csptCache,
 } from '../core/state.ts';
 import { fetchWithAuth, fetchMetricsHistory } from '../core/api.ts';
+import { apiGet } from '../core/api-client.ts';
 import { showToast, showConfirm, formatUptime, formatCompact } from '../core/ui.ts';
 import { createFpsSparkline } from '../core/chart-utils.ts';
 import { t } from '../core/i18n.ts';
-import { findConnection, getCompatibleInputs, getConnectionByField, updateConnection, detachConnection, isEditableEdge } from '../core/graph-connections.ts';
+import { findConnection, getCompatibleInputs, getConnectionByField, updateConnection, detachConnection, updateListSlotConnection, duplicateSubgraph, isEditableEdge, validateConnection, getDependents, checkSchemaDrift } from '../core/graph-connections.ts';
 import { showTypePicker } from '../core/icon-select.ts';
 import * as P from '../core/icon-paths.ts';
-import { readJson, isObject, isString, isNumber } from '../core/storage.ts';
+import { readJson, writeJson, isObject, isString, isNumber } from '../core/storage.ts';
 import { logError } from '../core/log.ts';
 
 // Local type guard for AnchoredRect — `JSON.parse` returns unknown and the
@@ -122,8 +124,33 @@ let _dragState: DragState | null = null;
 let _justDragged = false;
 let _dragListenersAdded = false;
 
-// Manual position overrides (persisted in memory; cleared on relayout)
+// Manual position overrides — persisted to localStorage so a hand-arranged
-let _manualPositions: Map<string, { x: number; y: number }> = new Map();
+// layout survives page reloads; cleared explicitly on relayout.
+const _POS_KEY = 'graph_node_positions';
+function _isPositionMap(v: unknown): v is Record<string, { x: number; y: number }> {
+    if (!isObject(v)) return false;
+    return Object.values(v).every(p => isObject(p) && isNumber((p as any).x) && isNumber((p as any).y));
+}
+function _loadManualPositions(): Map<string, { x: number; y: number }> {
+    const obj = readJson(_POS_KEY, _isPositionMap);
+    const map = new Map<string, { x: number; y: number }>();
+    if (obj) for (const [id, p] of Object.entries(obj)) map.set(id, { x: p.x, y: p.y });
+    return map;
+}
+function _saveManualPositions(): void {
+    const obj: Record<string, { x: number; y: number }> = {};
+    for (const [id, p] of _manualPositions) obj[id] = p;
+    writeJson(_POS_KEY, obj);
+}
+let _manualPositions: Map<string, { x: number; y: number }> = _loadManualPositions();
+
+// Node IDs that currently have a configuration issue (broken ref / cycle).
+let _issueIds: Set<string> = new Set();
+// Dangling references discovered during the last layout build.
+let _brokenRefs: BrokenRef[] = [];
+// Raw fetched entities by id — lets drop-resolution check which bindable slots
+// a target actually has (subtype-safe), without re-fetching.
+let _entitiesById: Map<string, any> = new Map();
 
 // Rubber-band selection state
 interface RubberBandState { startGraph: { x: number; y: number }; startClient: { x: number; y: number }; active: boolean; }
@@ -331,9 +358,18 @@ export async function loadGraphEditor(): Promise<void> {
         if (gc) gc.appendChild(overlay);
     }
 
+    // Dev safety net: warn once if the frontend connection map drifts from the
+    // backend schema (fire-and-forget; never blocks the graph).
+    void checkSchemaDrift();
+
     try {
         const entities = await _fetchAllEntities();
-        const { nodes, edges, bounds } = await computeLayout(entities);
+        // Index raw entities by id for subtype-safe bindable-slot resolution.
+        _entitiesById = new Map();
+        for (const arr of Object.values(entities)) {
+            if (Array.isArray(arr)) for (const ent of arr) if (ent && ent.id) _entitiesById.set(ent.id, ent);
+        }
+        const { nodes, edges, bounds, brokenRefs } = await computeLayout(entities);
 
         // Apply manual position overrides from previous drag operations
         _applyManualPositions(nodes, edges);
@@ -341,6 +377,7 @@ export async function loadGraphEditor(): Promise<void> {
         computePorts(nodes as any, edges);
         _nodeMap = nodes as any;
         _edges = edges;
+        _brokenRefs = brokenRefs;
         _bounds = _calcBounds(nodes);
         _renderGraph(container);
     } finally {
@@ -661,9 +698,181 @@ export async function graphRelayout(): Promise<void> {
         if (!ok) return;
     }
     _manualPositions.clear();
+    _saveManualPositions();
     await loadGraphEditor();
 }
 
+/* ── Health overlay (broken references + dependency cycles) ── */
+
+/** Humanize a reference field name for display (e.g. `capture_template_id` → `capture template`). */
+function _humanField(field: string): string {
+    return field.replace(/_id$/, '').replace(/\./g, ' ').replace(/_/g, ' ').trim();
+}
+
+/**
+ * Detect every node that participates in a directed dependency cycle.
+ * Iterative DFS with an explicit path stack (no deep recursion).
+ */
+function _detectCycles(nodeMap: Map<string, any>, edges: any[]): Set<string> {
+    const adj = new Map<string, string[]>();
+    for (const e of edges) {
+        if (!adj.has(e.from)) adj.set(e.from, []);
+        adj.get(e.from)!.push(e.to);
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map<string, number>();
+    const inCycle = new Set<string>();
+
+    for (const start of nodeMap.keys()) {
+        if (color.get(start)) continue; // already GRAY/BLACK
+        const stack: Array<{ id: string; i: number }> = [{ id: start, i: 0 }];
+        const path: string[] = [start];
+        color.set(start, GRAY);
+        while (stack.length) {
+            const frame = stack[stack.length - 1];
+            const neighbors = adj.get(frame.id) || [];
+            if (frame.i < neighbors.length) {
+                const v = neighbors[frame.i++];
+                const c = color.get(v) ?? WHITE;
+                if (c === GRAY) {
+                    // Back edge → mark the whole cycle from v to the current node.
+                    const idx = path.indexOf(v);
+                    if (idx >= 0) for (let k = idx; k < path.length; k++) inCycle.add(path[k]);
+                } else if (c === WHITE) {
+                    color.set(v, GRAY);
+                    path.push(v);
+                    stack.push({ id: v, i: 0 });
+                }
+            } else {
+                color.set(frame.id, BLACK);
+                path.pop();
+                stack.pop();
+            }
+        }
+    }
+    return inCycle;
+}
+
+/** Build the per-node issue map, render badges, and update the toolbar button. */
+function _computeAndMarkIssues(nodeGroup: SVGGElement): void {
+    const issues = new Map<string, string[]>();
+    const add = (id: string, msg: string): void => {
+        const list = issues.get(id);
+        if (list) list.push(msg); else issues.set(id, [msg]);
+    };
+
+    // Dangling references: the referrer still exists but its target is gone.
+    for (const br of _brokenRefs) {
+        add(br.by, t('graph.issue.broken_ref', { field: _humanField(br.field) }));
+    }
+
+    // Dependency cycles.
+    if (_nodeMap && _edges) {
+        for (const id of _detectCycles(_nodeMap, _edges)) add(id, t('graph.issue.cycle'));
+    }
+
+    _issueIds = new Set(issues.keys());
+    markIssues(nodeGroup, issues);
+    _updateIssuesButton();
+}
+
+function _updateIssuesButton(): void {
+    const btn = document.getElementById('graph-issues-btn');
+    if (!btn) return;
+    const count = _issueIds.size;
+    const countEl = btn.querySelector('.graph-issues-count');
+    if (countEl) countEl.textContent = count > 0 ? String(count) : '';
+    (btn as HTMLElement).style.display = count > 0 ? '' : 'none';
+}
+
+/**
+ * Export the full wiring topology (nodes + edges + validation report) as a
+ * downloadable JSON file. This is the read-only half of "wiring blueprints":
+ * a shareable, inspectable snapshot. Re-importing/instantiating a blueprint
+ * (with id remapping) is a separate, larger feature.
+ */
+export async function graphExportTopology(): Promise<void> {
+    try {
+        const topo = await apiGet<unknown>('/graph');
+        const blob = new Blob([JSON.stringify(topo, null, 2)], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `ledgrab-graph-${new Date().toISOString().slice(0, 10)}.json`;
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        URL.revokeObjectURL(url);
+        showToast(t('graph.export_done'), 'success');
+    } catch (e) {
+        showToast(e instanceof Error ? e.message : t('graph.export_failed'), 'error');
+    }
+}
+
+/**
+ * Duplicate the current node selection server-side. The backend clones the
+ * value / colour-strip sources in the selection (full config preserved, no
+ * secrets crossing the wire), rewires references that point *within* the
+ * selection, and shares everything else. The graph then reloads with the new
+ * cluster selected.
+ */
+export async function graphDuplicateSelection(): Promise<void> {
+    const ids = [..._selectedIds];
+    if (ids.length === 0) {
+        showToast(t('graph.duplicate_none'), 'info');
+        return;
+    }
+    const res = await duplicateSubgraph(ids);
+    if (!res) {
+        showToast(t('graph.duplicate_failed'), 'error');
+        return;
+    }
+    const newIds = Object.values(res.id_map || {});
+    if (newIds.length === 0) {
+        showToast(t('graph.duplicate_none_eligible'), 'info');
+        return;
+    }
+    await loadGraphEditor();
+    _selectedIds = new Set(newIds);
+    const nodeGroup = document.querySelector('.graph-nodes') as SVGGElement | null;
+    if (nodeGroup) updateSelection(nodeGroup, _selectedIds);
+    const hasWarn = !!res.warnings?.length;
+    showToast(
+        t(hasWarn ? 'graph.duplicate_done_warn' : 'graph.duplicate_done', { count: newIds.length }),
+        hasWarn ? 'info' : 'success',
+    );
+}
+
+/** Frame and highlight all nodes flagged with configuration issues. */
+export function graphShowIssues(): void {
+    if (_issueIds.size === 0 || !_nodeMap || !_canvas) {
+        showToast(t('graph.issues_none'), 'info');
+        return;
+    }
+    const ng = document.querySelector('.graph-nodes') as SVGGElement | null;
+    const eg = document.querySelector('.graph-edges') as SVGGElement | null;
+    _selectedIds = new Set(_issueIds);
+    if (ng) {
+        updateSelection(ng, _selectedIds);
+        ng.querySelectorAll('.graph-node').forEach((n: any) => {
+            n.style.opacity = _issueIds.has(n.getAttribute('data-id')) ? '1' : '0.2';
+        });
+    }
+    if (eg) clearEdgeHighlights(eg);
+
+    // Fit the viewport to the bounding box of the flagged nodes.
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const id of _issueIds) {
+        const n = _nodeMap.get(id);
+        if (!n) continue;
+        minX = Math.min(minX, n.x); minY = Math.min(minY, n.y);
+        maxX = Math.max(maxX, n.x + n.width); maxY = Math.max(maxY, n.y + n.height);
+    }
+    if (minX !== Infinity) {
+        _canvas.fitAll({ x: minX, y: minY, width: maxX - minX, height: maxY - minY }, true);
+    }
+}
+
 // Entity kind → window function to open add/create modal + icon path
 const _ico = (d: string): string => `<svg class="icon" viewBox="0 0 24 24">${d}</svg>`;
 const _w = window as any;
@@ -693,6 +902,25 @@ const ALL_CACHES = [
     automationsCacheObj, csptCache,
 ];
 
+// entity kind → its DataCache, so a kind-scoped watcher (create-and-connect)
+// only reacts to new entities of the expected kind, never an unrelated one.
+const KIND_CACHE: Record<string, { data?: any[]; subscribe(fn: (d: any) => void): void; unsubscribe(fn: (d: any) => void): void }> = {
+    device: devicesCache,
+    capture_template: captureTemplatesCache,
+    pp_template: ppTemplatesCache,
+    audio_template: audioTemplatesCache,
+    pattern_template: patternTemplatesCache,
+    picture_source: streamsCache,
+    audio_source: audioSourcesCache,
+    value_source: valueSourcesCache,
+    color_strip_source: colorStripSourcesCache,
+    sync_clock: syncClocksCache,
+    output_target: outputTargetsCache,
+    scene_preset: scenePresetsCache,
+    automation: automationsCacheObj,
+    cspt: csptCache,
+};
+
 export function graphAddEntity(): void {
     const items = ADD_ENTITY_MAP.map(item => ({
         value: item.kind,
@@ -712,16 +940,62 @@ export function graphAddEntity(): void {
     });
 }
 
+/**
+ * Drag-from-port onto empty canvas → offer to create a compatible consumer
+ * entity and wire it to the source in one gesture (the classic node-editor
+ * "drag out a new node" flow).
+ */
+function _promptCreateAndConnect(sourceKind: string, sourceId: string): void {
+    // Kinds that can consume this source (non-nested) and have an add action.
+    const kinds = [...new Set(getCompatibleInputs(sourceKind).map(c => c.targetKind))]
+        .filter(k => ADD_ENTITY_MAP.some(e => e.kind === k));
+    if (kinds.length === 0) {
+        showToast(t('graph.no_compatible_connection'), 'info');
+        return;
+    }
+    const items = kinds.map(k => {
+        const entry = ADD_ENTITY_MAP.find(e => e.kind === k)!;
+        return { value: k, icon: entry.icon, label: ENTITY_LABELS[k] || k.replace(/_/g, ' ') };
+    });
+    showTypePicker({
+        title: t('graph.create_and_connect'),
+        items,
+        onPick: (kind) => _createAndConnect(kind, sourceKind, sourceId),
+    });
+}
+
+/** Open the add-entity modal for `targetKind`, then wire the new entity to `sourceId`. */
+function _createAndConnect(targetKind: string, sourceKind: string, sourceId: string): void {
+    const entry = ADD_ENTITY_MAP.find(e => e.kind === targetKind);
+    if (!entry) return;
+    _watchForNewEntity((newId) => {
+        const matches = findConnection(targetKind, sourceKind);
+        if (matches.length === 1) {
+            _doConnect(newId, targetKind, matches[0].field, sourceId);
+        } else if (matches.length > 1) {
+            _promptConnectionField(matches, newId, targetKind, sourceId);
+        } else {
+            // No resolvable field — just refresh so the new node appears.
+            loadGraphEditor();
+        }
+    }, targetKind);
+    entry.fn();
+}
+
 // Watch for new entity creation after add-entity menu action
 let _entityWatchCleanup: (() => void) | null = null;
 
-function _watchForNewEntity(): void {
+function _watchForNewEntity(onNew?: (newId: string) => void, expectKind?: string): void {
     // Cleanup any previous watcher
     if (_entityWatchCleanup) _entityWatchCleanup();
 
+    // Scope to the expected kind's cache when given (create-and-connect), so the
+    // callback never fires for an unrelated entity that happens to appear first.
+    const caches = (expectKind && KIND_CACHE[expectKind]) ? [KIND_CACHE[expectKind]] : ALL_CACHES;
+
     // Snapshot all current IDs
     const knownIds = new Set<string>();
-    for (const cache of ALL_CACHES) {
+    for (const cache of caches) {
         for (const item of (cache.data || [])) {
             if (item.id) knownIds.add(item.id);
         }
@@ -731,9 +1005,12 @@ function _watchForNewEntity(): void {
         if (!Array.isArray(data)) return;
         for (const item of data) {
             if (item.id && !knownIds.has(item.id)) {
-                // Found a new entity — reload graph and zoom to it
+                // Found a new entity.
                 const newId = item.id;
                 cleanup();
+                // Custom handler (e.g. create-and-connect) takes over.
+                if (onNew) { onNew(newId); return; }
+                // Default: reload graph and zoom to the new node.
                 loadGraphEditor().then(() => {
                     const node = _nodeMap?.get(newId);
                     if (node && _canvas) {
@@ -751,14 +1028,14 @@ function _watchForNewEntity(): void {
         }
     };
 
-    for (const cache of ALL_CACHES) cache.subscribe(handler);
+    for (const cache of caches) cache.subscribe(handler);
 
     // Auto-cleanup after 2 minutes (user might cancel the modal)
     const timeout = setTimeout(cleanup, 120_000);
 
     function cleanup() {
         clearTimeout(timeout);
-        for (const cache of ALL_CACHES) cache.unsubscribe(handler);
+        for (const cache of caches) cache.unsubscribe(handler);
         _entityWatchCleanup = null;
     }
 
@@ -829,6 +1106,9 @@ function _renderGraph(container: HTMLElement): void {
     });
     markOrphans(nodeGroup, _nodeMap!, _edges!);
 
+    // Health overlay: flag dangling references and dependency cycles.
+    _computeAndMarkIssues(nodeGroup);
+
     // Animated flow dots for running nodes
     const runningIds = new Set<string>();
     for (const node of _nodeMap!.values()) {
@@ -845,6 +1125,8 @@ function _renderGraph(container: HTMLElement): void {
     _canvas.onZoomChange = (z) => {
         const label = container.querySelector('.graph-zoom-label');
         if (label) label.textContent = `${Math.round(z * 100)}%`;
+        // Reveal edge field labels once zoomed in enough to read them.
+        edgeGroup.classList.toggle('show-labels', z >= 0.9);
     };
 
     _canvas.onViewChange = (vp) => {
@@ -993,6 +1275,9 @@ function _renderGraph(container: HTMLElement): void {
     container.focus();
     // Re-focus when clicking inside the graph
     svgEl.addEventListener('pointerdown', () => container.focus());
+    // The toolbar markup hardcodes `disabled` on undo/redo; re-sync with the
+    // live stacks since this render may follow an undoable action.
+    _updateUndoRedoButtons();
     _initialized = true;
 }
 
@@ -1048,6 +1333,10 @@ function _graphHTML(): string {
                 <button class="btn-icon" onclick="graphRelayout()" title="${t('graph.relayout')}" data-collapse>
                     <svg class="icon" viewBox="0 0 24 24"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/></svg>
                 </button>
+                <button class="btn-icon graph-issues-btn" id="graph-issues-btn" onclick="graphShowIssues()" title="${t('graph.issues')}" style="display:none" data-collapse>
+                    <svg class="icon" viewBox="0 0 24 24"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
+                    <span class="graph-issues-count"></span>
+                </button>
                 <button class="btn-icon" onclick="graphToggleFullscreen()" title="${t('graph.fullscreen')} (F11)" data-collapse>
                     <svg class="icon" viewBox="0 0 24 24"><path d="M8 3H5a2 2 0 0 0-2 2v3"/><path d="M21 8V5a2 2 0 0 0-2-2h-3"/><path d="M3 16v3a2 2 0 0 0 2 2h3"/><path d="M16 21h3a2 2 0 0 0 2-2v-3"/></svg>
                 </button>
@@ -1098,6 +1387,14 @@ function _graphHTML(): string {
                     <svg class="icon" viewBox="0 0 24 24"><path d="M8 3H5a2 2 0 0 0-2 2v3"/><path d="M21 8V5a2 2 0 0 0-2-2h-3"/><path d="M3 16v3a2 2 0 0 0 2 2h3"/><path d="M16 21h3a2 2 0 0 0 2-2v-3"/></svg>
                     <span>${t('graph.fullscreen')}</span>
                 </button>
+                <button onclick="graphExportTopology(); closeToolbarOverflow()">
+                    <svg class="icon" viewBox="0 0 24 24"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="M7 10l5 5 5-5"/><path d="M12 15V3"/></svg>
+                    <span>${t('graph.export')}</span>
+                </button>
+                <button onclick="graphDuplicateSelection(); closeToolbarOverflow()">
+                    <svg class="icon" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+                    <span>${t('graph.duplicate')}</span>
+                </button>
                 <div class="graph-overflow-sep"></div>
                 <button id="graph-overflow-help" onclick="toggleGraphHelp(); closeToolbarOverflow()">
                     <svg class="icon" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><path d="M12 17h.01"/></svg>
@@ -1525,7 +1822,8 @@ function _onEditNode(node: any) {
     fnMap[node.kind]?.();
 }
 
-function _onDeleteNode(node: any) {
+/** Dispatch the per-entity delete (each shows its own confirm + handles API/cache). */
+function _deleteNodeRaw(node: any): void {
     const fnMap: any = {
         device: () => _w.removeDevice?.(node.id),
         capture_template: () => _w.deleteTemplate?.(node.id),
@@ -1545,6 +1843,30 @@ function _onDeleteNode(node: any) {
     fnMap[node.kind]?.();
 }
 
+// Guards the await gap (dependents fetch + confirm) against a double-fire from
+// rapid Delete presses or trash-button + Delete on the same node.
+const _deletingIds = new Set<string>();
+
+/**
+ * Single-node delete from the graph: first warn if other entities reference
+ * this one (their wiring would break), then hand off to the per-entity delete.
+ */
+async function _onDeleteNode(node: any): Promise<void> {
+    if (_deletingIds.has(node.id)) return;
+    _deletingIds.add(node.id);
+    try {
+        const deps = await getDependents(node.kind, node.id);
+        if (deps.length > 0) {
+            const names = deps.slice(0, 5).map(d => d.name).join(', ') + (deps.length > 5 ? ', …' : '');
+            const ok = await showConfirm(t('graph.delete_with_dependents_confirm', { count: deps.length, names }));
+            if (!ok) return;
+        }
+        _deleteNodeRaw(node);
+    } finally {
+        _deletingIds.delete(node.id);
+    }
+}
+
 async function _bulkDeleteSelected(): Promise<void> {
     const count = _selectedIds.size;
     if (count < 2) return;
@@ -1552,9 +1874,11 @@ async function _bulkDeleteSelected(): Promise<void> {
         (t('graph.bulk_delete_confirm') || 'Delete {count} selected entities?').replace('{count}', String(count))
     );
     if (!ok) return;
+    // Bulk uses the raw delegate — the single bulk confirm covers the batch, and
+    // per-node dependents prompts would be a dialog storm.
     for (const id of _selectedIds) {
         const node = _nodeMap?.get(id);
-        if (node) _onDeleteNode(node);
+        if (node) _deleteNodeRaw(node);
     }
     _selectedIds.clear();
 }
@@ -1991,17 +2315,37 @@ function _onDragPointerUp(): void {
         _justDragged = true;
         requestAnimationFrame(() => { _justDragged = false; });
 
+        const moved: Array<{ id: string; oldX: number; oldY: number; newX: number; newY: number }> = [];
+
         if (_dragState.multi) {
             _dragState.nodes.forEach(n => {
                 if (n.el) n.el.classList.remove('dragging');
                 const node = _nodeMap!.get(n.id);
-                if (node) _manualPositions.set(n.id, { x: node.x, y: node.y });
+                if (node) {
+                    _manualPositions.set(n.id, { x: node.x, y: node.y });
+                    moved.push({ id: n.id, oldX: n.startX, oldY: n.startY, newX: node.x, newY: node.y });
+                }
             });
         } else {
             const ds = _dragState as DragStateSingle;
             ds.el.classList.remove('dragging');
             const node = _nodeMap!.get(ds.nodeId);
-            if (node) _manualPositions.set(ds.nodeId, { x: node.x, y: node.y });
+            if (node) {
+                _manualPositions.set(ds.nodeId, { x: node.x, y: node.y });
+                moved.push({ id: ds.nodeId, oldX: ds.startNode.x, oldY: ds.startNode.y, newX: node.x, newY: node.y });
+            }
+        }
+
+        // Persist the hand-arranged layout so it survives page reloads.
+        _saveManualPositions();
+
+        // Record an undoable move (skip no-op drags below the dead zone).
+        if (moved.some(m => m.oldX !== m.newX || m.oldY !== m.newY)) {
+            pushUndoAction({
+                label: t('graph.action.move'),
+                undo: async () => { for (const m of moved) _manualPositions.set(m.id, { x: m.oldX, y: m.oldY }); _saveManualPositions(); },
+                redo: async () => { for (const m of moved) _manualPositions.set(m.id, { x: m.newX, y: m.newY }); _saveManualPositions(); },
+            });
         }
 
         _bounds = _calcBounds(_nodeMap);
@@ -2201,11 +2545,26 @@ function _initPortDrag(svgEl: SVGSVGElement, nodeGroup: SVGGElement, _edgeGroup:
                 p.classList.add('graph-port-incompatible');
             }
         });
+
+        // Also highlight whole compatible target NODES, so a slot with no
+        // existing edge (and therefore no input port yet) is still droppable —
+        // the user can drop anywhere on the node body to wire an empty slot.
+        const compatibleKinds = new Set(compatible.map(c => c.targetKind));
+        nodeGroup.querySelectorAll('.graph-node').forEach(n => {
+            const nKind = n.getAttribute('data-kind');
+            const nId = n.getAttribute('data-id');
+            if (nId !== sourceNodeId && nKind && compatibleKinds.has(nKind)) {
+                n.classList.add('graph-node-compatible');
+            }
+        });
     }, true); // capture phase to beat node drag
 
     if (!_connectListenersAdded) {
         window.addEventListener('pointermove', _onConnectPointerMove);
         window.addEventListener('pointerup', _onConnectPointerUp);
+        // pointercancel (touch interruption, capture loss) must also tear down
+        // the drag — otherwise the temp edge, node highlights and blockPan stick.
+        window.addEventListener('pointercancel', _onConnectPointerUp);
         _connectListenersAdded = true;
     }
 }
@@ -2228,12 +2587,20 @@ function _onConnectPointerMove(e: PointerEvent): void {
 
     svgEl.querySelectorAll('.graph-port-drop-target').forEach(p => p.classList.remove('graph-port-drop-target'));
     if (port) port.classList.add('graph-port-drop-target');
+
+    // Highlight the compatible node under the cursor for drop-on-node wiring
+    // (only when not already hovering a specific port).
+    svgEl.querySelectorAll('.graph-node-drop-target').forEach(n => n.classList.remove('graph-node-drop-target'));
+    if (!port) {
+        const nodeUnder = elem?.closest?.('.graph-node-compatible');
+        if (nodeUnder) nodeUnder.classList.add('graph-node-drop-target');
+    }
 }
 
 function _onConnectPointerUp(e: PointerEvent): void {
     if (!_connectState) return;
 
-    const { sourceNodeId, sourceKind, portType, dragPath } = _connectState;
+    const { sourceNodeId, sourceKind, startX, startY, dragPath } = _connectState;
 
     // Clean up drag edge
     dragPath.remove();
@@ -2241,48 +2608,138 @@ function _onConnectPointerUp(e: PointerEvent): void {
     if (svgEl) svgEl.classList.remove('connecting');
     if (_canvas) _canvas.blockPan = false;
 
-    // Clean up port highlights
+    // Clean up port + node highlights
     const nodeGroup = document.querySelector('.graph-nodes') as SVGGElement | null;
     if (nodeGroup) {
         nodeGroup.querySelectorAll('.graph-port-compatible, .graph-port-incompatible, .graph-port-drop-target').forEach(p => {
             p.classList.remove('graph-port-compatible', 'graph-port-incompatible', 'graph-port-drop-target');
         });
+        nodeGroup.querySelectorAll('.graph-node-compatible, .graph-node-drop-target').forEach(n => {
+            n.classList.remove('graph-node-compatible', 'graph-node-drop-target');
+        });
     }
 
-    // Check if dropped on a compatible input port
     const elem = document.elementFromPoint(e.clientX, e.clientY);
     const targetPort = elem?.closest?.('.graph-port-in');
     if (targetPort) {
+        // Dropped on a specific input port — resolve by that port's edge type.
         const targetNodeId = targetPort.getAttribute('data-node-id') ?? '';
         const targetKind = targetPort.getAttribute('data-node-kind') ?? '';
         const targetPortType = targetPort.getAttribute('data-port-type') ?? '';
 
         if (targetNodeId !== sourceNodeId) {
-            // Find the matching connection
+            const matches = _availableMatches(findConnection(targetKind, sourceKind, targetPortType), targetNodeId);
-            const matches = findConnection(targetKind, sourceKind, targetPortType);
             if (matches.length === 1) {
                 _doConnect(targetNodeId, targetKind, matches[0].field, sourceNodeId);
             } else if (matches.length > 1) {
-                // Multiple possible fields (e.g., template → picture_source could be capture or pp template)
+                // Genuinely ambiguous: the same source kind feeds two distinct
-                // Resolve by source kind
+                // fields (e.g. an automation's activation vs. deactivation scene).
-                const exact = matches.find(m => m.sourceKind === sourceKind);
+                _promptConnectionField(matches, targetNodeId, targetKind, sourceNodeId);
-                if (exact) {
+            }
-                    _doConnect(targetNodeId, targetKind, exact.field, sourceNodeId);
+        }
+    } else {
+        // Dropped on the node body (or an empty slot that has no port yet):
+        // resolve every connectable field for this source→target pair. This is
+        // what makes unconnected slots wireable from the graph.
+        const targetNode = elem?.closest?.('.graph-node');
+        if (targetNode) {
+            const targetNodeId = targetNode.getAttribute('data-id') ?? '';
+            const targetKind = targetNode.getAttribute('data-kind') ?? '';
+            if (targetNodeId && targetNodeId !== sourceNodeId) {
+                const matches = _availableMatches(findConnection(targetKind, sourceKind), targetNodeId);
+                if (matches.length === 1) {
+                    _doConnect(targetNodeId, targetKind, matches[0].field, sourceNodeId);
+                } else if (matches.length > 1) {
+                    _promptConnectionField(matches, targetNodeId, targetKind, sourceNodeId);
+                } else {
+                    showToast(t('graph.no_compatible_connection'), 'info');
                 }
             }
+        } else if (_canvas) {
+            // Dropped on empty canvas — offer to create a compatible consumer
+            // and wire it (skip when the gesture was effectively a click).
+            const CREATE_CONNECT_MIN_DRAG = 40;  // graph units
+            const gp = _canvas.screenToGraph(e.clientX, e.clientY);
+            if (Math.hypot(gp.x - startX, gp.y - startY) > CREATE_CONNECT_MIN_DRAG) {
+                _promptCreateAndConnect(sourceKind, sourceNodeId);
+            }
         }
     }
 
     _connectState = null;
 }
 
+/**
+ * Keep only the slots the target entity actually exposes (subtype-safe) — a
+ * field is offered iff its first path segment is a key on the serialized entity.
+ * E.g. an "effect" strip offers `intensity`/`scale`, a "picture" strip offers
+ * `smoothing`; a processed strip offers `input_source_id`. Applies to ALL
+ * matches (bindable and top-level alike); reference fields are always emitted by
+ * `to_dict` so empty slots stay wireable.
+ */
+function _availableMatches<T extends { field: string }>(matches: T[], targetId: string): T[] {
+    const ent = _entitiesById.get(targetId);
+    if (!ent) return matches;  // no data (e.g. freshly created) → don't over-filter
+    // Offer a field only if the target entity actually exposes its slot (its
+    // first path segment is a key on the serialized entity). Reference fields
+    // are always emitted by `to_dict` even when empty, so empty slots stay
+    // wireable (B2); subtype-specific fields (e.g. processed-strip
+    // `input_source_id`) are correctly hidden on subtypes that lack them.
+    return matches.filter(m => m.field.split('.')[0] in ent);
+}
+
+/** Ask the user which field to wire when a source maps to multiple target fields. */
+function _promptConnectionField(
+    matches: Array<{ field: string }>,
+    targetNodeId: string,
+    targetKind: string,
+    sourceNodeId: string,
+): void {
+    showTypePicker({
+        title: t('graph.choose_connection'),
+        items: matches.map(m => ({ value: m.field, icon: _ico(P.link), label: _humanField(m.field) })),
+        onPick: (field) => { _doConnect(targetNodeId, targetKind, field, sourceNodeId); },
+    });
+}
+
+/** The id currently wired into (targetId, field), or '' if the slot is empty. */
+function _currentSourceFor(targetId: string, field: string): string {
+    const edge = _edges?.find(e => e.to === targetId && e.field === field);
+    return edge ? edge.from : '';
+}
+
 async function _doConnect(targetId: string, targetKind: string, field: string, sourceId: string): Promise<void> {
+    const prevSourceId = _currentSourceFor(targetId, field);
+    if (prevSourceId === sourceId) return;  // dropped onto the existing connection — no-op
+
+    // Pre-flight validation (existence + source kind + no dependency cycle).
+    const v = await validateConnection(targetKind, targetId, field, sourceId);
+    if (!v.ok) {
+        showToast(v.error || t('graph.connection_failed'), 'error');
+        return;
+    }
+
+    // Confirm before overwriting an already-occupied slot.
+    if (prevSourceId) {
+        const confirmed = await showConfirm(t('graph.replace_connection_confirm'));
+        if (!confirmed) return;
+    }
+
     const ok = await updateConnection(targetId, targetKind, field, sourceId);
     if (ok) {
-        showToast(t('graph.connection_updated') || 'Connection updated', 'success');
+        // Record an undoable action that restores the previous slot occupant.
+        // The inverse ops throw on failure so `_undo`/`_redo` can keep the
+        // action on its stack instead of silently desyncing (updateConnection
+        // returns false rather than throwing on API error).
+        pushUndoAction({
+            label: t('graph.action.connect'),
+            undo: async () => { if (!(await updateConnection(targetId, targetKind, field, prevSourceId))) throw new Error(t('graph.connection_failed')); },
+            redo: async () => { if (!(await updateConnection(targetId, targetKind, field, sourceId))) throw new Error(t('graph.connection_failed')); },
+        });
+        showToast(t('graph.connection_updated'), 'success');
         await loadGraphEditor();
     } else {
-        showToast(t('graph.connection_failed') || 'Failed to update connection', 'error');
+        showToast(t('graph.connection_failed'), 'error');
     }
 }
 
@@ -2311,31 +2768,35 @@ export async function graphUndo(): Promise<void> { await _undo(); }
 export async function graphRedo(): Promise<void> { await _redo(); }
 
 async function _undo(): Promise<void> {
-    if (_undoStack.length === 0) { showToast(t('graph.nothing_to_undo') || 'Nothing to undo', 'info'); return; }
+    if (_undoStack.length === 0) { showToast(t('graph.nothing_to_undo'), 'info'); return; }
     const action = _undoStack.pop()!;
     try {
         await action.undo();
         _redoStack.push(action);
-        showToast(t('graph.undone') || `Undone: ${action.label}`, 'info');
+        showToast(t('graph.undone'), 'info');
         _updateUndoRedoButtons();
         await loadGraphEditor();
     } catch (e) {
-        showToast(e.message, 'error');
+        // The inverse op failed — keep the action on the undo stack so the
+        // user can retry, and surface the error instead of a false success.
+        _undoStack.push(action);
+        showToast(e instanceof Error ? e.message : String(e), 'error');
         _updateUndoRedoButtons();
     }
 }
 
 async function _redo(): Promise<void> {
-    if (_redoStack.length === 0) { showToast(t('graph.nothing_to_redo') || 'Nothing to redo', 'info'); return; }
+    if (_redoStack.length === 0) { showToast(t('graph.nothing_to_redo'), 'info'); return; }
     const action = _redoStack.pop()!;
     try {
         await action.redo();
         _undoStack.push(action);
-        showToast(t('graph.redone') || `Redone: ${action.label}`, 'info');
+        showToast(t('graph.redone'), 'info');
         _updateUndoRedoButtons();
         await loadGraphEditor();
     } catch (e) {
-        showToast(e.message, 'error');
+        _redoStack.push(action);
+        showToast(e instanceof Error ? e.message : String(e), 'error');
         _updateUndoRedoButtons();
     }
 }
@@ -2402,13 +2863,43 @@ export function toggleGraphHelp(): void {
 
 /* ── Edge context menu (right-click to detach) ── */
 
+/**
+ * Detach a connection and record an undoable action that restores it.
+ * @param prevSourceId the id previously wired into the slot (for undo)
+ */
+async function _doDetach(to: string, targetKind: string, field: string, prevSourceId: string): Promise<boolean> {
+    const ok = await detachConnection(to, targetKind, field);
+    if (ok) {
+        if (prevSourceId) {
+            pushUndoAction({
+                label: t('graph.action.disconnect'),
+                undo: async () => { if (!(await updateConnection(to, targetKind, field, prevSourceId))) throw new Error(t('graph.connection_failed')); },
+                redo: async () => { if (!(await detachConnection(to, targetKind, field))) throw new Error(t('graph.disconnect_failed')); },
+            });
+        }
+        showToast(t('graph.connection_removed'), 'success');
+        await loadGraphEditor();
+    } else {
+        showToast(t('graph.disconnect_failed'), 'error');
+    }
+    return ok;
+}
+
 function _onEdgeContextMenu(edgePath: Element, e: MouseEvent, container: HTMLElement): void {
     _dismissEdgeContextMenu();
 
     const field = edgePath.getAttribute('data-field') || '';
+    // List-slot edges (composite layers / mapped zones) aren't editable through
+    // the flat (to, field) path, but each carries its slot index so it can be
+    // re-wired individually.
+    if (edgePath.getAttribute('data-slot-list')) {
+        _showListSlotRewireMenu(edgePath, e, container);
+        return;
+    }
     if (!isEditableEdge(field)) return;  // nested fields can't be detached from graph
 
     const toId = edgePath.getAttribute('data-to') ?? '';
+    const fromId = edgePath.getAttribute('data-from') ?? '';
     const toNode = _nodeMap?.get(toId);
     if (!toNode) return;
 
@@ -2419,19 +2910,13 @@ function _onEdgeContextMenu(edgePath: Element, e: MouseEvent, container: HTMLEle
 
     const btn = document.createElement('button');
     btn.className = 'graph-edge-menu-item danger';
-    btn.textContent = t('graph.disconnect') || 'Disconnect';
+    btn.textContent = t('graph.disconnect');
     btn.addEventListener('click', async () => {
         try {
             _dismissEdgeContextMenu();
-            const ok = await detachConnection(toId, toNode.kind, field);
+            await _doDetach(toId, toNode.kind, field, fromId);
-            if (ok) {
-                showToast(t('graph.connection_removed') || 'Connection removed', 'success');
-                await loadGraphEditor();
-            } else {
-                showToast(t('graph.disconnect_failed') || 'Failed to disconnect', 'error');
-            }
         } catch (err) {
-            showToast(`${t('graph.disconnect_failed') || 'Failed to disconnect'}: ${err instanceof Error ? err.message : String(err)}`, 'error');
+            showToast(`${t('graph.disconnect_failed')}: ${err instanceof Error ? err.message : String(err)}`, 'error');
         }
     });
     menu.appendChild(btn);
@@ -2447,20 +2932,80 @@ function _dismissEdgeContextMenu(): void {
     }
 }
 
-async function _detachSelectedEdge(): Promise<void> {
+/**
-    if (!_selectedEdge) return;
+ * Re-wire menu for a list-slot edge (a composite layer or mapped zone source).
-    const { to, field, targetKind } = _selectedEdge;
+ * Each such edge carries `data-slot-*`, so we can replace just that one
-    _selectedEdge = null;
+ * element's reference and leave its siblings (and its own other settings)
+ * untouched. The picker lists every node of the source's kind; the backend
+ * rejects self-reference / cycles.
+ */
+function _showListSlotRewireMenu(edgePath: Element, e: MouseEvent, container: HTMLElement): void {
+    const toId = edgePath.getAttribute('data-to') ?? '';        // composite/mapped owner
+    const fromId = edgePath.getAttribute('data-from') ?? '';     // current source occupant
+    const listField = edgePath.getAttribute('data-slot-list') ?? '';
+    const index = parseInt(edgePath.getAttribute('data-slot-index') ?? '', 10);
+    const refField = edgePath.getAttribute('data-slot-ref') ?? '';
+    const toNode = _nodeMap?.get(toId);
+    if (!toNode || Number.isNaN(index)) return;
 
-    const ok = await detachConnection(to, targetKind, field);
+    const sourceKind = _nodeMap?.get(fromId)?.kind ?? 'color_strip_source';
+    const candidates = [...(_nodeMap?.values() ?? [])]
+        .filter((n: any) => n.kind === sourceKind && n.id !== toId && n.id !== fromId)
+        .sort((a: any, b: any) => (a.name || a.id).localeCompare(b.name || b.id));
+
+    const menu = document.createElement('div');
+    menu.className = 'graph-edge-menu';
+    menu.style.left = `${e.clientX - container.getBoundingClientRect().left}px`;
+    menu.style.top = `${e.clientY - container.getBoundingClientRect().top}px`;
+
+    const btn = document.createElement('button');
+    btn.className = 'graph-edge-menu-item';
+    btn.textContent = t('graph.rewire');
+    btn.addEventListener('click', () => {
+        _dismissEdgeContextMenu();
+        if (candidates.length === 0) { showToast(t('graph.no_compatible_connection'), 'info'); return; }
+        showTypePicker({
+            title: t('graph.rewire_choose_source'),
+            items: candidates.map((n: any) => ({ value: n.id, icon: _ico(P.link), label: n.name || n.id })),
+            onPick: (newSourceId: string) => { void _doListSlotRewire(toId, toNode.kind, listField, index, refField, newSourceId, fromId); },
+        });
+    });
+    menu.appendChild(btn);
+
+    container.querySelector('.graph-container')!.appendChild(menu);
+    _edgeContextMenu = menu;
+}
+
+/** Re-wire one list slot (composite layer / mapped zone) and record an undoable action. */
+async function _doListSlotRewire(
+    targetId: string, targetKind: string, listField: string, index: number,
+    refField: string, newSourceId: string, prevSourceId: string,
+): Promise<void> {
+    if (newSourceId === prevSourceId) return;
+    // Pass the expected current occupant so the write refuses if the slot was
+    // reordered/edited out-of-band (positional `index` could otherwise hit the
+    // wrong element). Each step expects the slot to still hold what it replaces.
+    const ok = await updateListSlotConnection(targetId, targetKind, listField, index, refField, newSourceId, prevSourceId);
     if (ok) {
-        showToast(t('graph.connection_removed') || 'Connection removed', 'success');
+        pushUndoAction({
+            label: t('graph.action.rewire'),
+            undo: async () => { if (!(await updateListSlotConnection(targetId, targetKind, listField, index, refField, prevSourceId, newSourceId))) throw new Error(t('graph.connection_failed')); },
+            redo: async () => { if (!(await updateListSlotConnection(targetId, targetKind, listField, index, refField, newSourceId, prevSourceId))) throw new Error(t('graph.connection_failed')); },
+        });
+        showToast(t('graph.connection_updated'), 'success');
         await loadGraphEditor();
     } else {
-        showToast(t('graph.disconnect_failed') || 'Failed to disconnect', 'error');
+        showToast(t('graph.connection_failed'), 'error');
     }
 }
 
+async function _detachSelectedEdge(): Promise<void> {
+    if (!_selectedEdge) return;
+    const { from, to, field, targetKind } = _selectedEdge;
+    _selectedEdge = null;
+    await _doDetach(to, targetKind, field, from);
+}
+
 /* ── Node hover FPS tooltip ── */
 
 let _hoverTooltip: HTMLDivElement | null = null;       // the <div> element, created once per graph render

server/src/ledgrab/static/js/features/targets.ts

@@ -171,6 +171,8 @@ class TargetEditorModal extends Modal {
             fps: _fpsWidget ? JSON.stringify(_fpsWidget.getValue()) : '30',
             keepalive_interval: (document.getElementById('target-editor-keepalive-interval') as HTMLInputElement).value,
             adaptive_fps: (document.getElementById('target-editor-adaptive-fps') as HTMLInputElement).checked,
+            max_milliamps: (document.getElementById('target-editor-max-milliamps') as HTMLInputElement).value,
+            milliamps_per_led: (document.getElementById('target-editor-ma-per-led') as HTMLInputElement).value,
             tags: JSON.stringify(_targetTagsInput ? _targetTagsInput.getValue() : []),
         };
     }
@@ -401,6 +403,8 @@ export async function showTargetEditor(targetId: string | null = null, cloneData
 
             (document.getElementById('target-editor-adaptive-fps') as HTMLInputElement).checked = target.adaptive_fps ?? false;
             (document.getElementById('target-editor-protocol') as HTMLSelectElement).value = target.protocol || 'ddp';
+            (document.getElementById('target-editor-max-milliamps') as HTMLInputElement).value = String(target.max_milliamps ?? 0);
+            (document.getElementById('target-editor-ma-per-led') as HTMLInputElement).value = String(target.milliamps_per_led ?? 55);
 
             _populateCssDropdown(target.color_strip_source_id || '');
             _ensureBrightnessWidget().setValue(target.brightness ?? 1.0);
@@ -419,6 +423,8 @@ export async function showTargetEditor(targetId: string | null = null, cloneData
 
             (document.getElementById('target-editor-adaptive-fps') as HTMLInputElement).checked = cloneData.adaptive_fps ?? false;
             (document.getElementById('target-editor-protocol') as HTMLSelectElement).value = cloneData.protocol || 'ddp';
+            (document.getElementById('target-editor-max-milliamps') as HTMLInputElement).value = String(cloneData.max_milliamps ?? 0);
+            (document.getElementById('target-editor-ma-per-led') as HTMLInputElement).value = String(cloneData.milliamps_per_led ?? 55);
 
             _populateCssDropdown(cloneData.color_strip_source_id || '');
             _ensureBrightnessWidget().setValue(cloneData.brightness ?? 1.0);
@@ -435,6 +441,8 @@ export async function showTargetEditor(targetId: string | null = null, cloneData
 
             (document.getElementById('target-editor-adaptive-fps') as HTMLInputElement).checked = false;
             (document.getElementById('target-editor-protocol') as HTMLSelectElement).value = 'ddp';
+            (document.getElementById('target-editor-max-milliamps') as HTMLInputElement).value = '0';
+            (document.getElementById('target-editor-ma-per-led') as HTMLInputElement).value = '55';
 
             _populateCssDropdown('');
             _ensureBrightnessWidget().setValue(1.0);
@@ -515,6 +523,8 @@ export async function saveTargetEditor() {
 
     const adaptiveFps = (document.getElementById('target-editor-adaptive-fps') as HTMLInputElement).checked;
     const protocol = (document.getElementById('target-editor-protocol') as HTMLSelectElement).value;
+    const maxMilliamps = Math.max(0, Math.round(Number((document.getElementById('target-editor-max-milliamps') as HTMLInputElement).value) || 0));
+    const milliampsPerLed = Math.max(1, Math.round(Number((document.getElementById('target-editor-ma-per-led') as HTMLInputElement).value) || 55));
 
     const payload: any = {
         name,
@@ -526,6 +536,8 @@ export async function saveTargetEditor() {
         keepalive_interval: standbyInterval,
         adaptive_fps: adaptiveFps,
         protocol,
+        max_milliamps: maxMilliamps,
+        milliamps_per_led: milliampsPerLed,
         tags: _targetTagsInput ? _targetTagsInput.getValue() : [],
     };
 

server/src/ledgrab/static/js/features/value-sources.ts

@@ -28,6 +28,7 @@ import {
     ICON_LED_PREVIEW, ICON_ACTIVITY, ICON_TIMER, ICON_MOVE_VERTICAL, ICON_CLOCK,
     ICON_MUSIC, ICON_TRENDING_UP, ICON_MAP_PIN, ICON_MONITOR, ICON_REFRESH, ICON_TRASH,
     ICON_HOME, ICON_RAINBOW, ICON_LINK, ICON_DROPLETS, ICON_GAMEPAD, ICON_X,
+    ICON_CHECK, ICON_FILE_TEXT,
 } from '../core/icons.ts';
 import { wrapCard } from '../core/card-colors.ts';
 import type { ModCardOpts, ModChipOpts } from '../core/mod-card.ts';
@@ -56,9 +57,10 @@ registerIconEntityType('value_source', makeSimpleIconAdapter<any>({
 import type { IconSelectItem } from '../core/icon-select.ts';
 import * as P from '../core/icon-paths.ts';
 import { EntitySelect } from '../core/entity-palette.ts';
+import * as JinjaEditor from '../core/jinja-editor.ts';
 import { loadPictureSources } from './streams.ts';
 import { hexToRgbArray, rgbArrayToHex } from './css-gradient-editor.ts';
-import type { ValueSource } from '../types.ts';
+import type { ValueSource, TemplateInput } from '../types.ts';
 
 export { getValueSourceIcon };
 
@@ -78,6 +80,14 @@ let _vsAnimColorClockEntitySelect: EntitySelect | null = null;
 let _vsHTTPEndpointEntitySelect: EntitySelect | null = null;
 let _vsTagsInput: TagInput | null = null;
 
+// ── Template value source editor state ──
+// (the bound inputs live in the DOM rows; read them via _readTemplateInputRows)
+const _vsTemplateInputSelects = new Map<HTMLElement, EntitySelect>();
+let _vsTemplateEditor: JinjaEditor.JinjaEditorHandle | null = null;
+let _templateValidateTimer: ReturnType<typeof setTimeout> | null = null;
+let _templateValidateGen = 0;
+let _vsTemplateInputUid = 0;
+
 class ValueSourceModal extends Modal {
     constructor() { super('value-source-modal'); }
 
@@ -95,6 +105,13 @@ class ValueSourceModal extends Modal {
         if (_vsAnimColorClockEntitySelect) { _vsAnimColorClockEntitySelect.destroy(); _vsAnimColorClockEntitySelect = null; }
         if (_vsGameIntegrationEntitySelect) { _vsGameIntegrationEntitySelect.destroy(); _vsGameIntegrationEntitySelect = null; }
         if (_vsHTTPEndpointEntitySelect) { _vsHTTPEndpointEntitySelect.destroy(); _vsHTTPEndpointEntitySelect = null; }
+        // Template editor: destroy all per-row EntitySelect portals + the highlighter
+        // and cancel any pending validation so stale responses are ignored.
+        _vsTemplateInputSelects.forEach(sel => sel.destroy());
+        _vsTemplateInputSelects.clear();
+        if (_vsTemplateEditor) { _vsTemplateEditor.destroy(); _vsTemplateEditor = null; }
+        if (_templateValidateTimer) { clearTimeout(_templateValidateTimer); _templateValidateTimer = null; }
+        _templateValidateGen++;
     }
 
     snapshotValues() {
@@ -146,6 +163,11 @@ class ValueSourceModal extends Modal {
             httpMin: (document.getElementById('value-source-http-min') as HTMLInputElement | null)?.value || '',
             httpMax: (document.getElementById('value-source-http-max') as HTMLInputElement | null)?.value || '',
             httpSmoothing: (document.getElementById('value-source-http-smoothing') as HTMLInputElement | null)?.value || '',
+            // Template value source
+            template: (document.getElementById('value-source-template-expression') as HTMLTextAreaElement | null)?.value || '',
+            templateInputs: JSON.stringify(_readTemplateInputRows()),
+            templateDefault: (document.getElementById('value-source-template-default-value') as HTMLInputElement | null)?.value || '',
+            templateEvalInterval: (document.getElementById('value-source-template-eval-interval') as HTMLInputElement | null)?.value || '',
         };
     }
 }
@@ -188,7 +210,7 @@ function _autoGenerateVSName() {
 
 /* ── Icon-grid type selector ──────────────────────────────────── */
 
-const VS_FLOAT_TYPE_KEYS = ['static', 'animated', 'audio', 'adaptive_time', 'adaptive_scene', 'daylight', 'ha_entity', 'system_metrics', 'game_event', 'http'];
+const VS_FLOAT_TYPE_KEYS = ['static', 'animated', 'audio', 'adaptive_time', 'adaptive_scene', 'daylight', 'ha_entity', 'system_metrics', 'game_event', 'http', 'template'];
 const VS_COLOR_TYPE_KEYS = ['static_color', 'animated_color', 'adaptive_time_color', 'gradient_map', 'css_extract'];
 const VS_TYPE_KEYS = [...VS_FLOAT_TYPE_KEYS, ...VS_COLOR_TYPE_KEYS];
 
@@ -396,6 +418,16 @@ function _onMetricChange(metric: string) {
     if (networkFields) networkFields.style.display = networkMetrics.includes(metric) ? '' : 'none';
     if (diskFields) diskFields.style.display = metric === 'disk_usage' ? '' : 'none';
     if (sensorFields) sensorFields.style.display = sensorMetrics.includes(metric) ? '' : 'none';
+    // The Normalize toggle only makes sense where a Min/Max range is shown
+    // (rangeMetrics). Percent/network/disk metrics have a fixed natural→0-1
+    // mapping in their reader, so "clamp the raw value as-is" would just
+    // saturate them; hide the toggle and force normalization on for those.
+    const normGroup = document.getElementById('value-source-sysmetric-normalize-group') as HTMLElement | null;
+    const normCb = document.getElementById('value-source-sysmetric-normalize') as HTMLInputElement | null;
+    const showNorm = rangeMetrics.includes(metric);
+    if (normGroup) normGroup.style.display = showNorm ? '' : 'none';
+    if (!showNorm && normCb) normCb.checked = true;
+    _syncVsNormalizeUI();
 }
 
 // ── Game Event Value Source helpers ──
@@ -597,6 +629,8 @@ export async function showValueSourceModal(editData: any, presetType: any = null
             (document.getElementById('value-source-min-ha-value') as HTMLInputElement).value = String(editData.min_ha_value ?? 0);
             (document.getElementById('value-source-max-ha-value') as HTMLInputElement).value = String(editData.max_ha_value ?? 100);
             _setSlider('value-source-ha-smoothing', editData.smoothing ?? 0);
+            (document.getElementById('value-source-ha-normalize') as HTMLInputElement).checked = editData.normalize !== false;
+            _syncVsNormalizeUI();
         } else if (editData.source_type === 'gradient_map') {
             _populateGradientInputDropdown(editData.value_source_id || '');
             _populateGradientEntityDropdown(editData.gradient_id || '');
@@ -616,7 +650,9 @@ export async function showValueSourceModal(editData: any, presetType: any = null
             (document.getElementById('value-source-sensor-label') as HTMLInputElement).value = editData.sensor_label || '';
             _setSlider('value-source-poll-interval', editData.poll_interval ?? 1.0);
             _setSlider('value-source-sysmetric-smoothing', editData.smoothing ?? 0);
+            (document.getElementById('value-source-sysmetric-normalize') as HTMLInputElement).checked = editData.normalize !== false;
             _onMetricChange(editData.metric || 'cpu_load');
+            _syncVsNormalizeUI();
         } else if (editData.source_type === 'game_event') {
             _populateVSGameIntegrationDropdown(editData.game_integration_id || '');
             _populateVSGameEventTypeDropdown(editData.event_type || 'health');
@@ -633,6 +669,17 @@ export async function showValueSourceModal(editData: any, presetType: any = null
             (document.getElementById('value-source-http-min') as HTMLInputElement).value = String(editData.min_value ?? 0);
             (document.getElementById('value-source-http-max') as HTMLInputElement).value = String(editData.max_value ?? 100);
             _setSlider('value-source-http-smoothing', editData.smoothing ?? 0);
+            (document.getElementById('value-source-http-normalize') as HTMLInputElement).checked = editData.normalize !== false;
+            _syncVsNormalizeUI();
+        } else if (editData.source_type === 'template') {
+            (document.getElementById('value-source-template-expression') as HTMLTextAreaElement).value = editData.template || '';
+            _setSlider('value-source-template-default-value', editData.default_value ?? 0.0);
+            (document.getElementById('value-source-template-default-value-display') as HTMLElement).textContent =
+                parseFloat(String(editData.default_value ?? 0.0)).toFixed(2);
+            (document.getElementById('value-source-template-eval-interval') as HTMLInputElement).value = String(editData.eval_interval ?? 0);
+            _ensureTemplateEditor();
+            _populateTemplateInputsUI(editData.inputs ?? []);
+            _runTemplateValidationDebounced();
         }
     } else {
         (document.getElementById('value-source-name') as HTMLInputElement).value = '';
@@ -683,6 +730,7 @@ export async function showValueSourceModal(editData: any, presetType: any = null
         (document.getElementById('value-source-min-ha-value') as HTMLInputElement).value = '0';
         (document.getElementById('value-source-max-ha-value') as HTMLInputElement).value = '100';
         _setSlider('value-source-ha-smoothing', 0);
+        (document.getElementById('value-source-ha-normalize') as HTMLInputElement).checked = true;
         // Gradient map defaults
         (document.getElementById('value-source-gradient-easing') as HTMLSelectElement).value = 'linear';
         // CSS extract defaults
@@ -697,6 +745,7 @@ export async function showValueSourceModal(editData: any, presetType: any = null
         (document.getElementById('value-source-sensor-label') as HTMLInputElement).value = '';
         _setSlider('value-source-poll-interval', 1.0);
         _setSlider('value-source-sysmetric-smoothing', 0);
+        (document.getElementById('value-source-sysmetric-normalize') as HTMLInputElement).checked = true;
         // HTTP value source defaults
         const httpJsonPath = document.getElementById('value-source-http-json-path') as HTMLInputElement | null;
         if (httpJsonPath) httpJsonPath.value = '';
@@ -707,6 +756,24 @@ export async function showValueSourceModal(editData: any, presetType: any = null
         const httpMax = document.getElementById('value-source-http-max') as HTMLInputElement | null;
         if (httpMax) httpMax.value = '100';
         _setSlider('value-source-http-smoothing', 0);
+        const httpNormalize = document.getElementById('value-source-http-normalize') as HTMLInputElement | null;
+        if (httpNormalize) httpNormalize.checked = true;
+        _syncVsNormalizeUI();
+        // Template value source defaults
+        const tmplExpr = document.getElementById('value-source-template-expression') as HTMLTextAreaElement | null;
+        if (tmplExpr) tmplExpr.value = '';
+        _setSlider('value-source-template-default-value', 0.0);
+        const tmplDefDisp = document.getElementById('value-source-template-default-value-display') as HTMLElement | null;
+        if (tmplDefDisp) tmplDefDisp.textContent = '0.00';
+        const tmplEval = document.getElementById('value-source-template-eval-interval') as HTMLInputElement | null;
+        if (tmplEval) tmplEval.value = '0';
+        if (presetType === 'template') {
+            _ensureTemplateEditor();
+            _populateTemplateInputsUI([]);
+            _runTemplateValidationDebounced();
+        } else {
+            _populateTemplateInputsUI([]);
+        }
         _autoGenerateVSName();
     }
 
@@ -763,6 +830,19 @@ export function onValueSourceTypeChange() {
         // before the integrations tab has been visited.
         httpEndpointsCache.fetch().then(() => _populateVSHTTPEndpointDropdown(''));
     }
+    const templateSec = document.getElementById('value-source-template-section') as HTMLElement | null;
+    if (templateSec) templateSec.style.display = type === 'template' ? '' : 'none';
+    if (type === 'template') {
+        _ensureTemplateEditor();
+        _runTemplateValidationDebounced();
+    } else {
+        // Leaving template type — cancel any pending/in-flight validation so a
+        // stale response cannot re-disable save on a non-template form, then
+        // restore the button.
+        if (_templateValidateTimer) { clearTimeout(_templateValidateTimer); _templateValidateTimer = null; }
+        _templateValidateGen++;
+        _setVSSaveEnabled(true);
+    }
     (document.getElementById('value-source-adaptive-range-section') as HTMLElement).style.display =
         (type === 'adaptive_time' || type === 'adaptive_scene' || type === 'daylight') ? '' : 'none';
 
@@ -815,6 +895,35 @@ function _syncDaylightVSSpeedVisibility() {
     (document.getElementById('value-source-daylight-speed-group') as HTMLElement).style.display = rt ? 'none' : '';
 }
 
+// ── Normalize toggle (magnitude sources: ha_entity / system_metrics / http) ──
+
+export function onValueSourceNormalizeChange() {
+    _syncVsNormalizeUI();
+}
+
+// Grey out + disable the Min/Max range inputs when a magnitude source is in
+// clamp-passthrough mode (normalize off) — they are inert there. Only the
+// visible section's pair is relevant, but syncing all three is harmless.
+function _syncVsNormalizeUI() {
+    const groups: Array<[string, string[]]> = [
+        ['value-source-ha-normalize', ['value-source-min-ha-value', 'value-source-max-ha-value']],
+        ['value-source-sysmetric-normalize', ['value-source-sysmetric-min', 'value-source-sysmetric-max']],
+        ['value-source-http-normalize', ['value-source-http-min', 'value-source-http-max']],
+    ];
+    for (const [cbId, inputIds] of groups) {
+        const cb = document.getElementById(cbId) as HTMLInputElement | null;
+        if (!cb) continue;
+        const on = cb.checked;
+        for (const id of inputIds) {
+            const inp = document.getElementById(id) as HTMLInputElement | null;
+            if (!inp) continue;
+            inp.disabled = !on;
+            const fg = inp.closest('.form-group') as HTMLElement | null;
+            if (fg) fg.style.opacity = on ? '' : '0.45';
+        }
+    }
+}
+
 // ── Save ──────────────────────────────────────────────────────
 
 export async function saveValueSource() {
@@ -889,6 +998,7 @@ export async function saveValueSource() {
         payload.min_ha_value = parseFloat((document.getElementById('value-source-min-ha-value') as HTMLInputElement).value);
         payload.max_ha_value = parseFloat((document.getElementById('value-source-max-ha-value') as HTMLInputElement).value);
         payload.smoothing = parseFloat((document.getElementById('value-source-ha-smoothing') as HTMLInputElement).value);
+        payload.normalize = (document.getElementById('value-source-ha-normalize') as HTMLInputElement).checked;
         if (!payload.ha_source_id) {
             errorEl.textContent = t('value_source.ha_source') + ' required';
             errorEl.style.display = '';
@@ -932,6 +1042,7 @@ export async function saveValueSource() {
         payload.sensor_label = (document.getElementById('value-source-sensor-label') as HTMLInputElement).value;
         payload.poll_interval = parseFloat((document.getElementById('value-source-poll-interval') as HTMLInputElement).value) || 1.0;
         payload.smoothing = parseFloat((document.getElementById('value-source-sysmetric-smoothing') as HTMLInputElement).value) || 0;
+        payload.normalize = (document.getElementById('value-source-sysmetric-normalize') as HTMLInputElement).checked;
     } else if (sourceType === 'game_event') {
         payload.game_integration_id = (document.getElementById('value-source-game-integration') as HTMLSelectElement).value;
         payload.event_type = (document.getElementById('value-source-game-event-type') as HTMLSelectElement).value;
@@ -952,6 +1063,7 @@ export async function saveValueSource() {
         payload.min_value = parseFloat((document.getElementById('value-source-http-min') as HTMLInputElement).value) || 0;
         payload.max_value = parseFloat((document.getElementById('value-source-http-max') as HTMLInputElement).value) || 100;
         payload.smoothing = parseFloat((document.getElementById('value-source-http-smoothing') as HTMLInputElement).value) || 0;
+        payload.normalize = (document.getElementById('value-source-http-normalize') as HTMLInputElement).checked;
         if (!payload.http_endpoint_id) {
             errorEl.textContent = t('value_source.http.endpoint_required');
             errorEl.style.display = '';
@@ -962,6 +1074,26 @@ export async function saveValueSource() {
             errorEl.style.display = '';
             return;
         }
+    } else if (sourceType === 'template') {
+        const inputs = _getTemplateInputsFromUI();
+        if (inputs === null) return;  // toast already shown
+        payload.template = (document.getElementById('value-source-template-expression') as HTMLTextAreaElement).value;
+        payload.inputs = inputs;
+        payload.default_value = parseFloat((document.getElementById('value-source-template-default-value') as HTMLInputElement).value) || 0.0;
+        const evalRaw = (document.getElementById('value-source-template-eval-interval') as HTMLInputElement).value.trim();
+        payload.eval_interval = evalRaw === '' ? null : (parseFloat(evalRaw) || 0);
+        if (!payload.template.trim()) {
+            errorEl.textContent = t('value_source.template.error.invalid_expr');
+            errorEl.style.display = '';
+            return;
+        }
+        // Final server-side gate: block save when the expression is invalid.
+        const result = await _validateTemplateRequest(payload.template, inputs, id || undefined);
+        if (result && result.valid === false) {
+            errorEl.textContent = (result.errors && result.errors[0]) || result.error || t('value_source.template.error.invalid_expr');
+            errorEl.style.display = '';
+            return;
+        }
     }
 
     try {
@@ -1373,6 +1505,7 @@ const VALUE_BADGE: Record<string, string> = {
     gradient_map: 'VALUE · MAP',
     css_extract: 'VALUE · STRIP',
     system_metrics: 'VALUE · SYS',
+    template: 'VALUE · EXPR',
 };
 
 function _valueSourceChipsAndExtras(src: ValueSource): { chips: ModChipOpts[]; metaText: string; extra: string } {
@@ -1503,6 +1636,16 @@ function _valueSourceChipsAndExtras(src: ValueSource): { chips: ModChipOpts[]; m
         const metricLabel = t(`value_source.metric.${(src as any).metric}`) || (src as any).metric;
         chips.push({ icon: ICON_ACTIVITY, text: metricLabel });
         metaText = metricLabel;
+    } else if (src.source_type === 'template') {
+        const inputs = (src as any).inputs || [];
+        const nInputs = inputs.length;
+        const expr = ((src as any).template || '').trim();
+        chips.push({
+            icon: ICON_FILE_TEXT,
+            text: `${nInputs} ${nInputs === 1 ? t('value_source.template.input_count_one') : t('value_source.template.input_count')}`,
+        });
+        if (expr) chips.push({ icon: ICON_ACTIVITY, text: expr.length > 28 ? expr.slice(0, 27) + '…' : expr });
+        metaText = `${t('value_source.type.template')} · ${nInputs} ${t('value_source.template.input_count')}`;
     }
 
     return { chips, metaText, extra };
@@ -1970,3 +2113,302 @@ function _populateCSSSourceDropdown(selectedId: string) {
         });
     }
 }
+
+// ── Template (Jinja expression) helpers ────────────────────────
+
+/** Reserved identifiers an input variable may NOT shadow. */
+const TEMPLATE_RESERVED_NAMES = new Set([
+    'min', 'max', 'abs', 'round', 'clamp', 'raw', 'range', 'dict', 'namespace',
+]);
+const TEMPLATE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Lazily attach the syntax-highlighting overlay to the expression textarea. */
+function _ensureTemplateEditor() {
+    const ta = document.getElementById('value-source-template-expression') as HTMLTextAreaElement | null;
+    if (!ta) return;
+    if (_vsTemplateEditor) { _vsTemplateEditor.refresh(); return; }
+    _vsTemplateEditor = JinjaEditor.create({
+        textarea: ta,
+        getInputNames: () => _readTemplateInputRows().map(i => i.name).filter(Boolean),
+        onChange: () => _runTemplateValidationDebounced(),
+    });
+}
+
+/** Bound-input names that are currently valid identifiers (for the highlighter + hints). */
+function _currentTemplateVarNames(): string[] {
+    return _readTemplateInputRows()
+        .map(i => i.name)
+        .filter(n => TEMPLATE_IDENT_RE.test(n));
+}
+
+/**
+ * Append one `.template-input-row` (a variable-name field + a value-source
+ * EntitySelect + a remove button). Invoked from the inline add button.
+ */
+export function addTemplateInput(name: string = '', vsId: string = '') {
+    const list = document.getElementById('value-source-template-inputs-list');
+    if (!list) return;
+
+    const row = document.createElement('div');
+    row.className = 'template-input-row';
+
+    const nameInput = document.createElement('input');
+    nameInput.type = 'text';
+    nameInput.className = 'template-input-name';
+    nameInput.placeholder = t('value_source.template.input_name');
+    nameInput.value = name;
+    nameInput.spellcheck = false;
+    nameInput.autocomplete = 'off';
+
+    const select = document.createElement('select');
+    select.id = `value-source-template-input-${++_vsTemplateInputUid}`;
+    const floatSources = _templateFloatSources();
+    select.innerHTML = `<option value=""></option>` + floatSources.map(s =>
+        `<option value="${escapeHtml(s.id)}"${s.id === vsId ? ' selected' : ''}>${escapeHtml(s.name)}</option>`
+    ).join('');
+    select.value = vsId || '';
+
+    const removeBtn = document.createElement('button');
+    removeBtn.type = 'button';
+    removeBtn.className = 'btn btn-icon btn-danger btn-sm';
+    removeBtn.innerHTML = ICON_TRASH;
+    removeBtn.setAttribute('aria-label', t('common.remove') || 'Remove');
+
+    row.appendChild(nameInput);
+    row.appendChild(select);
+    row.appendChild(removeBtn);
+    // Remove any "no inputs yet" placeholder before adding a real row.
+    const empty = list.querySelector('.template-inputs-empty');
+    if (empty) empty.remove();
+    list.appendChild(row);
+
+    const es = new EntitySelect({
+        target: select,
+        getItems: () => _templateFloatSources().map(s => ({
+            value: s.id,
+            label: s.name,
+            icon: getValueSourceIcon(s.source_type),
+            desc: s.source_type,
+        })),
+        placeholder: t('palette.search'),
+        allowNone: true,
+        noneLabel: '—',
+        onChange: () => _runTemplateValidationDebounced(),
+    });
+    _vsTemplateInputSelects.set(select, es);
+
+    nameInput.addEventListener('input', () => {
+        _vsTemplateEditor?.refresh();
+        _runTemplateValidationDebounced();
+    });
+
+    removeBtn.addEventListener('click', () => {
+        const sel = _vsTemplateInputSelects.get(select);
+        if (sel) { sel.destroy(); _vsTemplateInputSelects.delete(select); }
+        row.remove();
+        if (!list.querySelector('.template-input-row')) _showTemplateInputsEmpty(list);
+        _vsTemplateEditor?.refresh();
+        _renderTemplateHintVars();
+        _runTemplateValidationDebounced();
+    });
+
+    _renderTemplateHintVars();
+}
+
+/** Float value sources eligible to bind, excluding the source being edited. */
+function _templateFloatSources(): ValueSource[] {
+    const selfId = (document.getElementById('value-source-id') as HTMLInputElement).value || undefined;
+    return _cachedValueSources.filter(v => v.return_type === 'float' && v.id !== selfId);
+}
+
+function _showTemplateInputsEmpty(list: HTMLElement) {
+    const empty = document.createElement('div');
+    empty.className = 'template-inputs-empty';
+    empty.textContent = t('value_source.template.inputs.empty');
+    list.appendChild(empty);
+}
+
+/** Raw row read — no validation, no toast (used by snapshot + the live validator). */
+function _readTemplateInputRows(): TemplateInput[] {
+    const rows = document.querySelectorAll('#value-source-template-inputs-list .template-input-row');
+    const out: TemplateInput[] = [];
+    rows.forEach(row => {
+        const name = (row.querySelector('.template-input-name') as HTMLInputElement)?.value.trim() ?? '';
+        const select = row.querySelector('select') as HTMLSelectElement | null;
+        out.push({ name, value_source_id: select?.value || '' });
+    });
+    return out;
+}
+
+/**
+ * Validated read for save: every name must be a unique, non-reserved, valid
+ * identifier. Shows a toast and returns null on the first failure.
+ */
+function _getTemplateInputsFromUI(): TemplateInput[] | null {
+    const rows = _readTemplateInputRows();
+    const seen = new Set<string>();
+    for (const inp of rows) {
+        if (!inp.name) {
+            showToast(t('value_source.template.error.missing_input'), 'error');
+            return null;
+        }
+        if (!TEMPLATE_IDENT_RE.test(inp.name)) {
+            showToast(`${t('value_source.template.error.invalid_name')}: ${inp.name}`, 'error');
+            return null;
+        }
+        if (TEMPLATE_RESERVED_NAMES.has(inp.name)) {
+            showToast(`${t('value_source.template.error.reserved_name')}: ${inp.name}`, 'error');
+            return null;
+        }
+        if (seen.has(inp.name)) {
+            showToast(`${t('value_source.template.error.duplicate_name')}: ${inp.name}`, 'error');
+            return null;
+        }
+        seen.add(inp.name);
+    }
+    return rows;
+}
+
+/** Rebuild the inputs list from scratch (destroying any leaked EntitySelects). */
+function _populateTemplateInputsUI(inputs: TemplateInput[]) {
+    _vsTemplateInputSelects.forEach(sel => sel.destroy());
+    _vsTemplateInputSelects.clear();
+    const list = document.getElementById('value-source-template-inputs-list');
+    if (!list) return;
+    list.innerHTML = '';
+    if (inputs.length === 0) {
+        _showTemplateInputsEmpty(list);
+    } else {
+        inputs.forEach(i => addTemplateInput(i.name, i.value_source_id));
+    }
+    _vsTemplateEditor?.refresh();
+    _renderTemplateHintVars();
+}
+
+/** Paint the live list of bound variable chips into the hints panel. */
+function _renderTemplateHintVars() {
+    const host = document.getElementById('value-source-template-hint-vars');
+    if (!host) return;
+    const names = _currentTemplateVarNames();
+    if (names.length === 0) {
+        host.innerHTML = `<span class="jinja-hints-empty">${escapeHtml(t('value_source.template.hints.no_inputs'))}</span>`;
+        return;
+    }
+    host.innerHTML = names
+        .map(n => `<span class="tok-var-chip">${escapeHtml(n)}</span>`)
+        .join('');
+}
+
+// ── Live validation (debounced + generation-tagged) ────────────
+
+interface TemplateValidateResult {
+    valid: boolean;
+    error: string | null;
+    errors: string[];
+    warnings: string[];
+    variables: string[];
+}
+
+/** Enable/disable the value-source modal's primary (save) button. */
+function _setVSSaveEnabled(enabled: boolean) {
+    const btn = document.querySelector('#value-source-modal .modal-footer .btn-primary') as HTMLButtonElement | null;
+    if (btn) btn.disabled = !enabled;
+}
+
+function _runTemplateValidationDebounced() {
+    if (_vsTemplateEditor) _vsTemplateEditor.refresh();
+    _renderTemplateHintVars();
+    if (_templateValidateTimer) clearTimeout(_templateValidateTimer);
+    _templateValidateTimer = setTimeout(() => { void _validateTemplate(); }, 300);
+}
+
+/** POST the current expression/inputs to the validate endpoint (no UI side effects). */
+async function _validateTemplateRequest(
+    template: string, inputs: TemplateInput[], id?: string,
+): Promise<TemplateValidateResult | null> {
+    try {
+        const resp = await fetchWithAuth('/value-sources/validate-template', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ template, inputs, ...(id ? { id } : {}) }),
+        });
+        if (!resp.ok) return null;
+        return await resp.json() as TemplateValidateResult;
+    } catch {
+        return null;
+    }
+}
+
+/** Live validator: paints inline error/ok/warn state and gates the save button. */
+async function _validateTemplate() {
+    const editor = document.querySelector('#value-source-template-section .jinja-editor') as HTMLElement | null;
+    const errEl = document.getElementById('value-source-template-error') as HTMLElement | null;
+    const okEl = document.getElementById('value-source-template-ok') as HTMLElement | null;
+    const warnEl = document.getElementById('value-source-template-warn') as HTMLElement | null;
+    const ta = document.getElementById('value-source-template-expression') as HTMLTextAreaElement | null;
+    if (!ta) return;
+
+    // If the user switched away from template while this was pending, do nothing.
+    if ((document.getElementById('value-source-type') as HTMLSelectElement).value !== 'template') {
+        _setVSSaveEnabled(true);
+        return;
+    }
+
+    const template = ta.value;
+    // Drop blank-name rows: TemplateInput.name is min_length=1 server-side, so
+    // posting a half-typed row would 422 and silently blank the live validator.
+    const inputs = _readTemplateInputRows().filter(i => i.name.trim());
+    const id = (document.getElementById('value-source-id') as HTMLInputElement).value || undefined;
+
+    const gen = ++_templateValidateGen;
+    const result = await _validateTemplateRequest(template, inputs, id);
+    if (gen !== _templateValidateGen) return;  // a newer request superseded this one
+    // The user may have switched away from template during the await — never
+    // touch a non-template form's save state.
+    if ((document.getElementById('value-source-type') as HTMLSelectElement).value !== 'template') {
+        _setVSSaveEnabled(true);
+        return;
+    }
+
+    const setSaveEnabled = _setVSSaveEnabled;
+
+    const clearMsgs = () => {
+        if (errEl) { errEl.style.display = 'none'; errEl.textContent = ''; }
+        if (okEl) { okEl.style.display = 'none'; okEl.innerHTML = ''; }
+        if (warnEl) { warnEl.style.display = 'none'; warnEl.textContent = ''; }
+    };
+
+    if (!result) {
+        // Network/endpoint failure — don't block the user; clear inline state.
+        editor?.classList.remove('field-invalid');
+        clearMsgs();
+        setSaveEnabled(true);
+        return;
+    }
+
+    clearMsgs();
+    if (result.valid === false) {
+        editor?.classList.add('field-invalid');
+        if (errEl) {
+            errEl.innerHTML = `${ICON_X}<span></span>`;
+            const span = errEl.querySelector('span');
+            if (span) span.textContent = (result.errors && result.errors[0]) || result.error || t('value_source.template.error.invalid_expr');
+            errEl.style.display = '';
+        }
+        setSaveEnabled(false);
+        return;
+    }
+
+    editor?.classList.remove('field-invalid');
+    setSaveEnabled(true);
+    if (okEl && template.trim()) {
+        okEl.innerHTML = `${ICON_CHECK}<span></span>`;
+        const span = okEl.querySelector('span');
+        if (span) span.textContent = t('value_source.template.valid');
+        okEl.style.display = '';
+    }
+    if (warnEl && result.warnings && result.warnings.length > 0) {
+        warnEl.textContent = result.warnings.join(' · ');
+        warnEl.style.display = '';
+    }
+}

server/src/ledgrab/static/js/global.d.ts

@@ -331,11 +331,13 @@ startTargetOverlay: (...args: any[]) => any;
     deleteValueSource: (...args: any[]) => any;
     onValueSourceTypeChange: (...args: any[]) => any;
     onDaylightVSRealTimeChange: (...args: any[]) => any;
+    onValueSourceNormalizeChange: (...args: any[]) => any;
     addSchedulePoint: (...args: any[]) => any;
     addAnimatedColor: (...args: any[]) => any;
     removeAnimatedColor: (...args: any[]) => any;
     addColorSchedulePoint: (...args: any[]) => any;
     removeColorSchedulePoint: (...args: any[]) => any;
+    addTemplateInput: (...args: any[]) => any;
     testValueSource: (...args: any[]) => any;
     closeTestValueSourceModal: (...args: any[]) => any;
 
@@ -377,6 +379,9 @@ startTargetOverlay: (...args: any[]) => any;
     graphZoomIn: (...args: any[]) => any;
     graphZoomOut: (...args: any[]) => any;
     graphRelayout: (...args: any[]) => any;
+    graphShowIssues: (...args: any[]) => any;
+    graphExportTopology: (...args: any[]) => any;
+    graphDuplicateSelection: (...args: any[]) => any;
     graphToggleFullscreen: (...args: any[]) => any;
     graphAddEntity: (...args: any[]) => any;
 

server/src/ledgrab/static/js/types.ts

@@ -76,6 +76,8 @@ export type {
     SystemMetricsValueSource,
     GameEventValueSource,
     HTTPValueSource,
+    TemplateValueSource,
+    TemplateInput,
     ValueSource,
     ValueSourceListResponse,
 } from './types/value-source.ts';

server/src/ledgrab/static/js/types/output-target.ts

@@ -50,6 +50,8 @@ export interface LedOutputTarget extends OutputTargetBase {
     min_brightness_threshold?: BindableFloat;
     adaptive_fps: boolean;
     protocol: string;
+    max_milliamps?: number;
+    milliamps_per_led?: number;
 }
 
 export type HALightSourceKind = 'css' | 'color_vs';

server/src/ledgrab/static/js/types/value-source.ts

@@ -9,7 +9,12 @@ export type ValueSourceType =
     | 'adaptive_time' | 'adaptive_scene' | 'daylight'
     | 'static_color' | 'animated_color' | 'adaptive_time_color'
     | 'ha_entity' | 'gradient_map' | 'css_extract'
-    | 'system_metrics' | 'game_event' | 'http';
+    | 'system_metrics' | 'game_event' | 'http' | 'template';
+
+export interface TemplateInput {
+    name: string;
+    value_source_id: string;
+}
 
 export interface SchedulePoint {
     time: string;
@@ -121,6 +126,7 @@ export interface HAEntityValueSource extends ValueSourceBase {
     min_ha_value: number;
     max_ha_value: number;
     smoothing: number;
+    normalize: boolean;
 }
 
 export interface GradientMapValueSource extends ValueSourceBase {
@@ -150,6 +156,7 @@ export interface SystemMetricsValueSource extends ValueSourceBase {
     sensor_label: string;
     poll_interval: number;
     smoothing: number;
+    normalize: boolean;
 }
 
 export interface GameEventValueSource extends ValueSourceBase {
@@ -173,6 +180,16 @@ export interface HTTPValueSource extends ValueSourceBase {
     min_value: number;
     max_value: number;
     smoothing: number;
+    normalize: boolean;
+}
+
+export interface TemplateValueSource extends ValueSourceBase {
+    source_type: 'template';
+    return_type: 'float';
+    template: string;
+    inputs: TemplateInput[];
+    default_value: number;
+    eval_interval?: number | null;
 }
 
 export type ValueSource =
@@ -190,7 +207,8 @@ export type ValueSource =
     | CSSExtractValueSource
     | SystemMetricsValueSource
     | GameEventValueSource
-    | HTTPValueSource;
+    | HTTPValueSource
+    | TemplateValueSource;
 
 export interface ValueSourceListResponse {
     sources: ValueSource[];

server/src/ledgrab/static/locales/en.json

@@ -103,6 +103,7 @@
   "templates.engine.wgc.desc": "Windows Graphics Capture",
   "templates.engine.demo.desc": "Animated test pattern (demo mode)",
   "templates.engine.mediaprojection.desc": "Native Android screen capture",
+  "templates.engine.android_camera.desc": "On-device camera capture (Camera2)",
   "templates.config": "Configuration",
   "templates.config.show": "Show configuration",
   "templates.config.none": "No additional configuration",
@@ -362,6 +363,9 @@
   "device.mqtt_topic": "MQTT Topic:",
   "device.mqtt_topic.hint": "MQTT topic path for publishing pixel data (e.g. mqtt://ledgrab/device/name)",
   "device.mqtt_topic.placeholder": "mqtt://ledgrab/device/living-room",
+  "device.mqtt_source": "MQTT Broker:",
+  "device.mqtt_source.hint": "Which MQTT broker this device publishes to. Manage brokers under Integrations → MQTT Sources. Leave unset to use the first available broker.",
+  "device.mqtt_source.none": "— First available broker",
   "device.ws_url": "Connection URL:",
   "device.ws_url.hint": "WebSocket URL for clients to connect and receive LED data",
   "device.openrgb.url": "OpenRGB URL:",
@@ -1222,6 +1226,10 @@
   "automations.rule.application.match_type.topmost_fullscreen.desc": "Foreground + fullscreen",
   "automations.rule.application.match_type.fullscreen": "Fullscreen",
   "automations.rule.application.match_type.fullscreen.desc": "Any fullscreen app",
+  "automations.rule.application.apps.hint_android": "Package names, one per line (e.g. com.netflix.mediaclient)",
+  "automations.rule.application.search_apps": "Filter apps...",
+  "automations.rule.application.no_apps": "No apps found",
+  "automations.rule.application.usage_access_required": "Needs Usage Access. On your LedGrab TV, open the app and tap 'Grant usage access'.",
   "automations.rule.time_of_day": "Time of Day",
   "automations.rule.time_of_day.desc": "Time range",
   "automations.rule.time_of_day.start_time": "Start Time:",
@@ -1982,6 +1990,8 @@
   "value_source.daylight.speed.hint": "Cycle speed multiplier. 1.0 = full day/night cycle in ~4 minutes. Higher values cycle faster.",
   "value_source.daylight.use_real_time": "Use Real Time:",
   "value_source.daylight.use_real_time.hint": "When enabled, the value follows the actual time of day. Speed is ignored.",
+  "value_source.normalize": "Normalize to 0–1:",
+  "value_source.normalize.hint": "On: rescale the raw value to 0–1 using Min/Max. Off: the value is clamped to 0–1 as-is (for sources that already report a 0–1 fraction). The raw value stays available to templates (raw[name]) and automations.",
   "value_source.daylight.enable_real_time": "Follow wall clock",
   "value_source.daylight.latitude": "Latitude:",
   "value_source.daylight.latitude.hint": "Your geographic latitude (-90 to 90). Steepens or flattens the sunrise/sunset edges of the cycle.",
@@ -2069,6 +2079,10 @@
   "targets.adaptive_fps.hint": "Automatically reduce send rate when the device becomes unresponsive, and gradually recover when it stabilizes. Recommended for WiFi devices with weak signal.",
   "targets.protocol": "Protocol:",
   "targets.protocol.hint": "DDP sends pixels via fast UDP (recommended for most setups). HTTP uses the JSON API — slower but reliable, limited to ~500 LEDs.",
+  "targets.power_limit": "Max current (ABL):",
+  "targets.power_limit.hint": "Caps the strip's estimated current draw to your power-supply budget to prevent brownouts (voltage sag, color shift, flicker) on bright/white scenes. Set it to your PSU's rated current, leaving some headroom. 0 = unlimited.",
+  "targets.power_limit.ma_suffix": "mA (0 = unlimited)",
+  "targets.power_limit.per_led": "mA per LED (full white):",
   "targets.protocol.ddp": "DDP (UDP)",
   "targets.protocol.ddp.desc": "Fast raw UDP packets — recommended",
   "targets.protocol.http": "HTTP",
@@ -2582,6 +2596,32 @@
   "graph.tooltip.fps": "FPS",
   "graph.tooltip.errors": "Errors",
   "graph.tooltip.uptime": "Uptime",
+  "graph.undone": "Undone",
+  "graph.redone": "Redone",
+  "graph.action.connect": "Connect",
+  "graph.action.disconnect": "Disconnect",
+  "graph.action.move": "Move node",
+  "graph.action.rewire": "Re-wire slot",
+  "graph.choose_connection": "Choose connection",
+  "graph.rewire": "Re-wire…",
+  "graph.rewire_choose_source": "Choose a new source",
+  "graph.issues": "Issues",
+  "graph.issues_none": "No issues found",
+  "graph.issue.broken_ref": "Broken reference: {field}",
+  "graph.issue.cycle": "Part of a dependency cycle",
+  "graph.replace_connection_confirm": "Replace the existing connection?",
+  "graph.no_compatible_connection": "No compatible connection between these entities",
+  "graph.create_and_connect": "Create & connect…",
+  "graph.export": "Export graph (JSON)",
+  "graph.export_done": "Graph exported",
+  "graph.export_failed": "Failed to export graph",
+  "graph.duplicate": "Duplicate selection",
+  "graph.duplicate_none": "Select one or more nodes to duplicate",
+  "graph.duplicate_none_eligible": "Nothing duplicable in the selection (only value & colour-strip sources)",
+  "graph.duplicate_done": "Duplicated {count} source(s)",
+  "graph.duplicate_done_warn": "Duplicated {count} source(s) — some references could not be remapped",
+  "graph.duplicate_failed": "Failed to duplicate selection",
+  "graph.delete_with_dependents_confirm": "This entity is used by {count} other(s): {names}. Delete it and break those connections?",
   "automation.enabled": "Automation enabled",
   "automation.disabled": "Automation disabled",
   "scene_preset.activated": "Preset activated",
@@ -3044,6 +3084,39 @@
   "value_source.http.modulator.hint": "Only used when this source drives brightness or color. Automation rules read the raw extracted value and ignore these settings.",
   "value_source.http.endpoint_required": "HTTP endpoint is required",
   "value_source.http.interval_invalid": "Interval must be at least 1 second",
+  "value_source.type.template": "Jinja Template",
+  "value_source.type.template.desc": "Combine bound inputs with a sandboxed Jinja expression to compute a 0-1 value.",
+  "value_source.template.expression": "Expression:",
+  "value_source.template.expression.hint": "A sandboxed Jinja expression returning a number. Bound inputs are available by name; use raw[name] for the un-normalized value.",
+  "value_source.template.expression.placeholder": "clamp((temp - 18) / 10, 0, 1)",
+  "value_source.template.inputs": "Inputs:",
+  "value_source.template.inputs.hint": "Bind float value sources to variable names you reference in the expression.",
+  "value_source.template.inputs.empty": "No inputs yet. Click + to bind a value source.",
+  "value_source.template.add_input": "+ Add Input",
+  "value_source.template.input_name": "variable name",
+  "value_source.template.input_count": "inputs",
+  "value_source.template.input_count_one": "input",
+  "value_source.template.default_value": "Default Value:",
+  "value_source.template.default_value.hint": "Output used when the expression cannot be evaluated (e.g. an input is missing).",
+  "value_source.template.eval_interval": "Eval Interval (s):",
+  "value_source.template.eval_interval.hint": "How often to re-evaluate the expression. 0 = every poll (re-evaluate as fast as the inputs update).",
+  "value_source.template.valid": "Expression is valid",
+  "value_source.template.hints.title": "Expression help",
+  "value_source.template.hints.inputs_title": "Bound inputs",
+  "value_source.template.hints.no_inputs": "No inputs bound yet",
+  "value_source.template.hints.globals_title": "Globals",
+  "value_source.template.hints.globals": "min(a, b), max(a, b), abs(x), round(x), clamp(x, lo, hi)",
+  "value_source.template.hints.raw_title": "Raw values",
+  "value_source.template.hints.raw": "raw[name] gives the un-normalized value of an input that has one.",
+  "value_source.template.hints.examples_title": "Examples",
+  "value_source.template.hints.time": "Tip: for time-of-day logic, bind an Adaptive (Time) or Daylight source as an input.",
+  "value_source.template.error.invalid_expr": "Expression is invalid",
+  "value_source.template.error.cycle": "This expression would create a dependency cycle",
+  "value_source.template.error.missing_input": "Every input needs a variable name",
+  "value_source.template.error.invalid_name": "Invalid variable name",
+  "value_source.template.error.reserved_name": "Reserved name cannot be used as an input",
+  "value_source.template.error.duplicate_name": "Duplicate input name",
+  "value_source.template.error.unbound": "Expression references an unbound variable",
   "automations.rule.http_poll": "HTTP Poll",
   "automations.rule.http_poll.desc": "Activate when the latest extracted value from an HTTP value source matches.",
   "automations.rule.http_poll.hint": "Compares the latest extracted value against your input. The value source decides what gets extracted (raw body or JSON path).",

server/src/ledgrab/static/locales/ru.json

@@ -158,6 +158,7 @@
   "templates.engine.wgc.desc": "Windows Graphics Capture",
   "templates.engine.demo.desc": "Тестовый анимированный шаблон (демо)",
   "templates.engine.mediaprojection.desc": "Нативный захват экрана Android",
+  "templates.engine.android_camera.desc": "Захват камеры устройства (Camera2)",
   "templates.config": "Конфигурация",
   "templates.config.show": "Показать конфигурацию",
   "templates.config.none": "Нет дополнительных настроек",
@@ -417,6 +418,9 @@
   "device.mqtt_topic": "MQTT Топик:",
   "device.mqtt_topic.hint": "MQTT топик для публикации пиксельных данных (напр. mqtt://ledgrab/device/name)",
   "device.mqtt_topic.placeholder": "mqtt://ledgrab/device/гостиная",
+  "device.mqtt_source": "MQTT Брокер:",
+  "device.mqtt_source.hint": "К какому MQTT-брокеру публикует это устройство. Брокеры настраиваются в разделе Интеграции → Источники MQTT. Оставьте пустым, чтобы использовать первый доступный брокер.",
+  "device.mqtt_source.none": "— Первый доступный брокер",
   "device.ws_url": "URL подключения:",
   "device.ws_url.hint": "WebSocket URL для подключения клиентов и получения LED данных",
   "device.openrgb.url": "OpenRGB URL:",
@@ -1256,6 +1260,10 @@
   "automations.rule.application.match_type.topmost_fullscreen.desc": "В фокусе + полный экран",
   "automations.rule.application.match_type.fullscreen": "Полный экран",
   "automations.rule.application.match_type.fullscreen.desc": "Любое полноэкранное",
+  "automations.rule.application.apps.hint_android": "Имена пакетов, по одному в строке (напр. com.netflix.mediaclient)",
+  "automations.rule.application.search_apps": "Поиск приложений...",
+  "automations.rule.application.no_apps": "Приложения не найдены",
+  "automations.rule.application.usage_access_required": "Требуется доступ к статистике использования. Откройте LedGrab на телевизоре и нажмите «Разрешить доступ к статистике использования».",
   "automations.rule.time_of_day": "Время суток",
   "automations.rule.time_of_day.desc": "Диапазон времени",
   "automations.rule.time_of_day.start_time": "Время начала:",
@@ -1842,6 +1850,8 @@
   "value_source.daylight.speed.hint": "Множитель скорости цикла. 1.0 = полный цикл день/ночь за ~4 минуты.",
   "value_source.daylight.use_real_time": "Реальное время:",
   "value_source.daylight.use_real_time.hint": "Значение следует за реальным временем суток. Скорость игнорируется.",
+  "value_source.normalize": "Нормализовать в 0–1:",
+  "value_source.normalize.hint": "Вкл.: масштабировать сырое значение в 0–1 по Min/Max. Выкл.: значение ограничивается диапазоном 0–1 как есть (для источников, уже выдающих долю 0–1). Сырое значение остаётся доступным в шаблонах (raw[name]) и автоматизациях.",
   "value_source.daylight.enable_real_time": "Следовать за часами",
   "value_source.daylight.latitude": "Широта:",
   "value_source.daylight.latitude.hint": "Географическая широта (-90 до 90). Делает переходы рассвета и заката круче или плавнее.",
@@ -1929,6 +1939,10 @@
   "targets.adaptive_fps.hint": "Автоматически снижает частоту отправки, когда устройство перестаёт отвечать, и постепенно восстанавливает её при стабилизации. Рекомендуется для WiFi-устройств со слабым сигналом.",
   "targets.protocol": "Протокол:",
   "targets.protocol.hint": "DDP отправляет пиксели по быстрому UDP (рекомендуется). HTTP использует JSON API — медленнее, но надёжнее, ограничение ~500 LED.",
+  "targets.power_limit": "Макс. ток (ABL):",
+  "targets.power_limit.hint": "Ограничивает расчётный ток ленты бюджетом блока питания, чтобы избежать просадок напряжения (сдвиг цвета, мерцание, перезагрузки) на ярких/белых сценах. Укажите номинальный ток вашего БП с запасом. 0 = без ограничения.",
+  "targets.power_limit.ma_suffix": "мА (0 = без ограничения)",
+  "targets.power_limit.per_led": "мА на светодиод (полный белый):",
   "targets.protocol.ddp": "DDP (UDP)",
   "targets.protocol.ddp.desc": "Быстрые UDP-пакеты — рекомендуется",
   "targets.protocol.http": "HTTP",
@@ -2264,6 +2278,32 @@
   "graph.tooltip.fps": "FPS",
   "graph.tooltip.errors": "Ошибки",
   "graph.tooltip.uptime": "Время работы",
+  "graph.undone": "Отменено",
+  "graph.redone": "Повторено",
+  "graph.action.connect": "Соединить",
+  "graph.action.disconnect": "Отсоединить",
+  "graph.action.move": "Переместить узел",
+  "graph.action.rewire": "Переподключить слот",
+  "graph.choose_connection": "Выберите соединение",
+  "graph.rewire": "Переподключить…",
+  "graph.rewire_choose_source": "Выберите новый источник",
+  "graph.issues": "Проблемы",
+  "graph.issues_none": "Проблем не найдено",
+  "graph.issue.broken_ref": "Битая ссылка: {field}",
+  "graph.issue.cycle": "Входит в цикл зависимостей",
+  "graph.replace_connection_confirm": "Заменить существующее соединение?",
+  "graph.no_compatible_connection": "Нет совместимого соединения между этими объектами",
+  "graph.create_and_connect": "Создать и соединить…",
+  "graph.export": "Экспорт графа (JSON)",
+  "graph.export_done": "Граф экспортирован",
+  "graph.export_failed": "Не удалось экспортировать граф",
+  "graph.duplicate": "Дублировать выбранное",
+  "graph.duplicate_none": "Выберите один или несколько узлов для дублирования",
+  "graph.duplicate_none_eligible": "В выборе нечего дублировать (только источники значений и цветовых лент)",
+  "graph.duplicate_done": "Продублировано источников: {count}",
+  "graph.duplicate_done_warn": "Продублировано источников: {count} — часть ссылок не удалось перепривязать",
+  "graph.duplicate_failed": "Не удалось дублировать выбранное",
+  "graph.delete_with_dependents_confirm": "Этот объект используется {count} другими: {names}. Удалить и разорвать эти связи?",
   "automation.enabled": "Автоматизация включена",
   "automation.disabled": "Автоматизация выключена",
   "scene_preset.activated": "Пресет активирован",
@@ -2726,6 +2766,39 @@
   "value_source.http.modulator.hint": "Используется только когда этот источник управляет яркостью или цветом. Правила автоматизации читают извлечённое значение в исходном виде и игнорируют эти настройки.",
   "value_source.http.endpoint_required": "Требуется HTTP-эндпоинт",
   "value_source.http.interval_invalid": "Интервал должен быть не меньше 1 секунды",
+  "value_source.type.template": "Шаблон Jinja",
+  "value_source.type.template.desc": "Объедините привязанные входы в изолированном выражении Jinja для вычисления значения 0-1.",
+  "value_source.template.expression": "Выражение:",
+  "value_source.template.expression.hint": "Изолированное выражение Jinja, возвращающее число. Привязанные входы доступны по имени; используйте raw[name] для ненормализованного значения.",
+  "value_source.template.expression.placeholder": "clamp((temp - 18) / 10, 0, 1)",
+  "value_source.template.inputs": "Входы:",
+  "value_source.template.inputs.hint": "Привяжите числовые источники значений к именам переменных, используемым в выражении.",
+  "value_source.template.inputs.empty": "Пока нет входов. Нажмите +, чтобы привязать источник значений.",
+  "value_source.template.add_input": "+ Добавить вход",
+  "value_source.template.input_name": "имя переменной",
+  "value_source.template.input_count": "входов",
+  "value_source.template.input_count_one": "вход",
+  "value_source.template.default_value": "Значение по умолчанию:",
+  "value_source.template.default_value.hint": "Значение на выходе, когда выражение нельзя вычислить (например, отсутствует вход).",
+  "value_source.template.eval_interval": "Интервал вычисления (с):",
+  "value_source.template.eval_interval.hint": "Как часто пересчитывать выражение. 0 = при каждом опросе (так быстро, как обновляются входы).",
+  "value_source.template.valid": "Выражение корректно",
+  "value_source.template.hints.title": "Справка по выражению",
+  "value_source.template.hints.inputs_title": "Привязанные входы",
+  "value_source.template.hints.no_inputs": "Входы ещё не привязаны",
+  "value_source.template.hints.globals_title": "Глобальные функции",
+  "value_source.template.hints.globals": "min(a, b), max(a, b), abs(x), round(x), clamp(x, lo, hi)",
+  "value_source.template.hints.raw_title": "Исходные значения",
+  "value_source.template.hints.raw": "raw[name] даёт ненормализованное значение входа, если оно есть.",
+  "value_source.template.hints.examples_title": "Примеры",
+  "value_source.template.hints.time": "Совет: для логики времени суток привяжите источник «Адаптивный (время)» или «Дневной цикл» как вход.",
+  "value_source.template.error.invalid_expr": "Некорректное выражение",
+  "value_source.template.error.cycle": "Это выражение создало бы циклическую зависимость",
+  "value_source.template.error.missing_input": "Каждому входу нужно имя переменной",
+  "value_source.template.error.invalid_name": "Некорректное имя переменной",
+  "value_source.template.error.reserved_name": "Зарезервированное имя нельзя использовать как вход",
+  "value_source.template.error.duplicate_name": "Повторяющееся имя входа",
+  "value_source.template.error.unbound": "Выражение ссылается на непривязанную переменную",
   "automations.rule.http_poll": "HTTP-опрос",
   "automations.rule.http_poll.desc": "Срабатывает, когда последнее значение HTTP-источника соответствует условию.",
   "automations.rule.http_poll.hint": "Сравнивает последнее извлечённое значение с вашим вводом. Что именно извлекается (тело или JSON-путь), задаётся в источнике-значении.",

server/src/ledgrab/static/locales/zh.json

@@ -156,6 +156,7 @@
   "templates.engine.wgc.desc": "Windows图形捕获",
   "templates.engine.demo.desc": "动画测试图案（演示模式）",
   "templates.engine.mediaprojection.desc": "原生Android屏幕捕获",
+  "templates.engine.android_camera.desc": "设备摄像头捕获 (Camera2)",
   "templates.config": "配置",
   "templates.config.show": "显示配置",
   "templates.config.none": "无额外配置",
@@ -415,6 +416,9 @@
   "device.mqtt_topic": "MQTT 主题：",
   "device.mqtt_topic.hint": "用于发布像素数据的 MQTT 主题路径（例如 mqtt://ledgrab/device/name）",
   "device.mqtt_topic.placeholder": "mqtt://ledgrab/device/客厅",
+  "device.mqtt_source": "MQTT 代理：",
+  "device.mqtt_source.hint": "此设备发布到哪个 MQTT 代理。在集成 → MQTT 源中管理代理。留空则使用第一个可用代理。",
+  "device.mqtt_source.none": "— 第一个可用代理",
   "device.ws_url": "连接 URL：",
   "device.ws_url.hint": "客户端连接并接收 LED 数据的 WebSocket URL",
   "device.openrgb.url": "OpenRGB URL：",
@@ -1252,6 +1256,10 @@
   "automations.rule.application.match_type.topmost_fullscreen.desc": "前台 + 全屏",
   "automations.rule.application.match_type.fullscreen": "全屏",
   "automations.rule.application.match_type.fullscreen.desc": "任意全屏应用",
+  "automations.rule.application.apps.hint_android": "包名，每行一个（例如 com.netflix.mediaclient）",
+  "automations.rule.application.search_apps": "筛选应用…",
+  "automations.rule.application.no_apps": "未找到应用",
+  "automations.rule.application.usage_access_required": "需要使用情况访问权限。在您的 LedGrab 电视上打开应用并点按「授予使用情况访问权限」。",
   "automations.rule.time_of_day": "时段",
   "automations.rule.time_of_day.desc": "时间范围",
   "automations.rule.time_of_day.start_time": "开始时间：",
@@ -1838,6 +1846,8 @@
   "value_source.daylight.speed.hint": "周期速度倍率。1.0 = 完整日夜周期约4分钟。",
   "value_source.daylight.use_real_time": "使用实时：",
   "value_source.daylight.use_real_time.hint": "启用后，数值跟随实际时间。速度设置将被忽略。",
+  "value_source.normalize": "归一化到 0–1：",
+  "value_source.normalize.hint": "开启：使用最小/最大值将原始值缩放到 0–1。关闭：直接将数值钳制到 0–1（适用于本身就输出 0–1 比例的来源）。原始值始终可在模板（raw[name]）和自动化中使用。",
   "value_source.daylight.enable_real_time": "跟随系统时钟",
   "value_source.daylight.latitude": "纬度：",
   "value_source.daylight.latitude.hint": "地理纬度（-90到90）。使日出/日落过渡更陡峭或更平缓。",
@@ -1925,6 +1935,10 @@
   "targets.adaptive_fps.hint": "当设备无响应时自动降低发送速率，稳定后逐步恢复。推荐用于信号较弱的WiFi设备。",
   "targets.protocol": "协议：",
   "targets.protocol.hint": "DDP通过快速UDP发送像素（推荐）。HTTP使用JSON API——较慢但可靠，限制约500个LED。",
+  "targets.power_limit": "最大电流 (ABL)：",
+  "targets.power_limit.hint": "将灯带的估算电流限制在电源预算内，以防止明亮/白色场景下的电压骤降（颜色偏移、闪烁、重启）。请设为电源的额定电流并留有余量。0 = 不限制。",
+  "targets.power_limit.ma_suffix": "mA（0 = 不限制）",
+  "targets.power_limit.per_led": "每颗 LED 电流（全白）：",
   "targets.protocol.ddp": "DDP (UDP)",
   "targets.protocol.ddp.desc": "快速UDP数据包 - 推荐",
   "targets.protocol.http": "HTTP",
@@ -2260,6 +2274,32 @@
   "graph.tooltip.fps": "帧率",
   "graph.tooltip.errors": "错误",
   "graph.tooltip.uptime": "运行时间",
+  "graph.undone": "已撤销",
+  "graph.redone": "已重做",
+  "graph.action.connect": "连接",
+  "graph.action.disconnect": "断开连接",
+  "graph.action.move": "移动节点",
+  "graph.action.rewire": "重新连接槽位",
+  "graph.choose_connection": "选择连接",
+  "graph.rewire": "重新连接…",
+  "graph.rewire_choose_source": "选择新的来源",
+  "graph.issues": "问题",
+  "graph.issues_none": "未发现问题",
+  "graph.issue.broken_ref": "无效引用：{field}",
+  "graph.issue.cycle": "属于依赖循环",
+  "graph.replace_connection_confirm": "替换现有连接？",
+  "graph.no_compatible_connection": "这些实体之间没有兼容的连接",
+  "graph.create_and_connect": "创建并连接…",
+  "graph.export": "导出图谱 (JSON)",
+  "graph.export_done": "图谱已导出",
+  "graph.export_failed": "导出图谱失败",
+  "graph.duplicate": "复制所选",
+  "graph.duplicate_none": "请选择一个或多个节点以复制",
+  "graph.duplicate_none_eligible": "所选内容中没有可复制的项（仅值源和色带源）",
+  "graph.duplicate_done": "已复制 {count} 个源",
+  "graph.duplicate_done_warn": "已复制 {count} 个源 — 部分引用无法重新映射",
+  "graph.duplicate_failed": "复制所选失败",
+  "graph.delete_with_dependents_confirm": "此实体被 {count} 个其他实体引用：{names}。删除并断开这些连接？",
   "automation.enabled": "自动化已启用",
   "automation.disabled": "自动化已禁用",
   "scene_preset.activated": "预设已激活",
@@ -2720,6 +2760,39 @@
   "value_source.http.modulator.hint": "仅当此源用于驱动亮度或颜色时使用。自动化规则会直接读取提取的原始值，并忽略这些设置。",
   "value_source.http.endpoint_required": "需要 HTTP 端点",
   "value_source.http.interval_invalid": "间隔至少为 1 秒",
+  "value_source.type.template": "Jinja 模板",
+  "value_source.type.template.desc": "使用沙盒化的 Jinja 表达式组合已绑定的输入，计算出 0-1 的值。",
+  "value_source.template.expression": "表达式：",
+  "value_source.template.expression.hint": "返回数字的沙盒化 Jinja 表达式。已绑定的输入可按名称使用；使用 raw[name] 获取未归一化的值。",
+  "value_source.template.expression.placeholder": "clamp((temp - 18) / 10, 0, 1)",
+  "value_source.template.inputs": "输入：",
+  "value_source.template.inputs.hint": "将浮点值源绑定到你在表达式中引用的变量名。",
+  "value_source.template.inputs.empty": "暂无输入。点击 + 绑定一个值源。",
+  "value_source.template.add_input": "+ 添加输入",
+  "value_source.template.input_name": "变量名",
+  "value_source.template.input_count": "个输入",
+  "value_source.template.input_count_one": "个输入",
+  "value_source.template.default_value": "默认值：",
+  "value_source.template.default_value.hint": "当表达式无法求值（例如缺少输入）时使用的输出值。",
+  "value_source.template.eval_interval": "求值间隔（秒）：",
+  "value_source.template.eval_interval.hint": "重新求值表达式的频率。0 = 每次轮询（随输入更新一样快地重新求值）。",
+  "value_source.template.valid": "表达式有效",
+  "value_source.template.hints.title": "表达式帮助",
+  "value_source.template.hints.inputs_title": "已绑定的输入",
+  "value_source.template.hints.no_inputs": "尚未绑定输入",
+  "value_source.template.hints.globals_title": "全局函数",
+  "value_source.template.hints.globals": "min(a, b), max(a, b), abs(x), round(x), clamp(x, lo, hi)",
+  "value_source.template.hints.raw_title": "原始值",
+  "value_source.template.hints.raw": "raw[name] 给出某个输入的未归一化值（如果有）。",
+  "value_source.template.hints.examples_title": "示例",
+  "value_source.template.hints.time": "提示：要实现一天中的时间逻辑，请将“自适应（时间）”或“日光周期”源绑定为输入。",
+  "value_source.template.error.invalid_expr": "表达式无效",
+  "value_source.template.error.cycle": "该表达式会造成依赖循环",
+  "value_source.template.error.missing_input": "每个输入都需要一个变量名",
+  "value_source.template.error.invalid_name": "变量名无效",
+  "value_source.template.error.reserved_name": "保留名称不能用作输入",
+  "value_source.template.error.duplicate_name": "输入名称重复",
+  "value_source.template.error.unbound": "表达式引用了未绑定的变量",
   "automations.rule.http_poll": "HTTP 轮询",
   "automations.rule.http_poll.desc": "当 HTTP 值源的最新提取值匹配时激活。",
   "automations.rule.http_poll.hint": "将最新的提取值与您的输入进行比较。提取的内容（原始响应体或 JSON 路径）由值源决定。",

server/src/ledgrab/static/sw.js

@@ -4,20 +4,233 @@
  * Strategy:
  *   - Static assets (/static/): stale-while-revalidate
  *   - API / config requests: network-only (device control must be live)
- *   - Navigation: network-first with offline fallback
+ *   - Navigation: network-first with branded offline fallback
  */
 
-const CACHE_NAME = 'ledgrab-v34';
+const CACHE_NAME = 'ledgrab-v35';
 
 // Only pre-cache static assets (no auth required).
 // Do NOT pre-cache '/' — it requires API key auth and would cache an error page.
+// The Orbitron brand font is precached so the offline page renders on-brand
+// even on a device that hasn't warmed the font cache yet.
 const PRECACHE_URLS = [
     '/static/dist/app.bundle.css',
     '/static/dist/app.bundle.js',
     '/static/icons/icon-192.png',
     '/static/icons/icon-512.png',
+    '/static/fonts/orbitron-700-latin.woff2',
 ];
 
+// Branded offline fallback shown when a navigation can't reach the server.
+// Self-contained (no CDN, no app CSS) so it renders with zero live network.
+// Mirrors the "Lumenworks" console aesthetic: pure-black panel, Orbitron brand
+// mark, channel-coral for the offline/alarm state, signal-green for restore.
+// A background probe self-heals the page — it reloads the instant the server
+// answers again, so a restarting server no longer leaves a dead-end screen.
+const OFFLINE_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="dark light">
+<title>LED Grab — Signal Lost</title>
+<style>
+  *{margin:0;padding:0;box-sizing:border-box}
+  :root{
+    --bg:#000;--line:#1c2027;
+    --ink:#eef2f7;--dim:#aeb7c4;--mute:#6b7480;
+    --coral:#ff5e5e;
+    --signal:#4caf50;--signal-hi:#6fd173;
+    --glow-coral:0 0 18px rgba(255,94,94,.55);
+    --glow-signal:0 0 10px rgba(76,175,80,.8);
+  }
+  @media (prefers-color-scheme: light){
+    :root{
+      --bg:#f6f8fb;--line:#dee3ea;
+      --ink:#0f1419;--dim:#41505f;--mute:#7b8694;
+      --coral:#d8392e;
+      --signal:#2e7d32;--signal-hi:#3d8b40;
+      --glow-coral:0 0 16px rgba(216,57,46,.30);
+      --glow-signal:0 0 10px rgba(46,125,50,.5);
+    }
+  }
+  @font-face{
+    font-family:'Orbitron';font-style:normal;font-weight:700;font-display:swap;
+    src:url('/static/fonts/orbitron-700-latin.woff2') format('woff2');
+  }
+  html,body{height:100%}
+  body{
+    background:var(--bg);color:var(--ink);
+    font-family:'Manrope','Segoe UI',system-ui,-apple-system,BlinkMacSystemFont,sans-serif;
+    -webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;
+    display:grid;place-items:center;min-height:100dvh;position:relative;overflow:hidden;
+    padding:calc(28px + env(safe-area-inset-top)) 24px calc(28px + env(safe-area-inset-bottom));
+  }
+  /* atmosphere: coral alarm vignette + faint signal floor */
+  body::before{
+    content:'';position:fixed;inset:0;z-index:0;pointer-events:none;
+    background:
+      radial-gradient(125% 80% at 50% -12%, rgba(255,94,94,.11), transparent 60%),
+      radial-gradient(100% 55% at 50% 118%, rgba(0,216,255,.045), transparent 60%);
+  }
+  /* fine equipment-panel scanlines */
+  body::after{
+    content:'';position:fixed;inset:0;z-index:0;pointer-events:none;opacity:.5;
+    mix-blend-mode:screen;
+    background:repeating-linear-gradient(0deg, rgba(255,255,255,.018) 0 1px, transparent 1px 3px);
+  }
+  @media (prefers-color-scheme: light){
+    body::after{opacity:.4;mix-blend-mode:multiply;
+      background:repeating-linear-gradient(0deg, rgba(0,0,0,.02) 0 1px, transparent 1px 3px)}
+  }
+  .panel{position:relative;z-index:1;width:min(460px,100%);
+    display:flex;flex-direction:column;align-items:center;text-align:center}
+  .panel>*{opacity:0;transform:translateY(10px);animation:rise .6s cubic-bezier(.16,1,.3,1) forwards}
+  .brand{animation-delay:.05s}.strip-wrap{animation-delay:.14s}.chip{animation-delay:.22s}
+  .headline{animation-delay:.30s}.copy{animation-delay:.38s}.btn{animation-delay:.46s}
+  .telemetry{animation-delay:.54s}.foot{animation-delay:.62s}
+  @keyframes rise{to{opacity:1;transform:none}}
+
+  .brand{display:flex;align-items:center;gap:11px;margin-bottom:32px}
+  .brand-dot{width:9px;height:9px;border-radius:50%;background:var(--coral);
+    box-shadow:var(--glow-coral);animation:beat 1.6s ease-in-out infinite}
+  .brand-name{font-family:'Orbitron','Segoe UI',sans-serif;font-weight:700;
+    font-size:.95rem;letter-spacing:.34em;text-indent:.34em;color:var(--ink)}
+  @keyframes beat{0%,100%{opacity:1}50%{opacity:.28}}
+
+  .strip-wrap{width:100%;margin-bottom:28px}
+  .strip{position:relative;display:flex;gap:7px;padding:15px 12px;overflow:hidden;
+    border:1px solid var(--line);border-radius:13px;
+    background:linear-gradient(180deg, rgba(255,255,255,.025), transparent)}
+  .strip i{flex:1 1 0;height:11px;border-radius:3px;background:var(--coral);opacity:.16;
+    transition:opacity .45s ease, background .45s ease, box-shadow .45s ease}
+  .strip::before{content:'';position:absolute;top:0;bottom:0;width:30%;left:-40%;
+    mix-blend-mode:screen;filter:blur(7px);
+    background:linear-gradient(90deg, transparent, var(--coral), transparent);
+    animation:sweep 2.4s linear infinite}
+  @keyframes sweep{0%{left:-42%}100%{left:112%}}
+
+  .chip{display:inline-flex;align-items:center;gap:9px;margin-bottom:24px;
+    font-family:'JetBrains Mono',ui-monospace,'Cascadia Code',monospace;
+    font-size:.66rem;font-weight:600;letter-spacing:.22em;text-transform:uppercase;
+    color:var(--coral);padding:5px 14px;border-radius:100px;
+    border:1px solid color-mix(in srgb, var(--coral) 38%, transparent)}
+  .chip b{width:7px;height:7px;border-radius:1px;background:var(--coral);
+    box-shadow:var(--glow-coral);animation:beat 1.6s ease-in-out infinite}
+
+  .headline{font-family:'Orbitron','Segoe UI',sans-serif;font-weight:700;
+    font-size:clamp(2.5rem,11.5vw,3.6rem);line-height:.92;letter-spacing:.015em;
+    text-transform:uppercase;color:var(--coral);text-shadow:0 0 26px rgba(255,94,94,.34);
+    margin-bottom:20px;animation:rise .6s cubic-bezier(.16,1,.3,1) forwards, flicker 5.5s 1.4s ease-in-out infinite}
+  .headline span{display:block;color:var(--ink);text-shadow:none}
+  @keyframes flicker{0%,93%,100%{opacity:1}94%{opacity:.55}96%{opacity:.85}97%{opacity:.4}}
+
+  .copy{max-width:35ch;color:var(--dim);font-size:.99rem;line-height:1.62;margin-bottom:32px}
+
+  .btn{position:relative;overflow:hidden;cursor:pointer;border:none;border-radius:11px;
+    padding:14px 36px;color:#04140a;background:var(--signal);
+    font-family:'JetBrains Mono',ui-monospace,monospace;font-weight:700;
+    font-size:.8rem;letter-spacing:.18em;text-transform:uppercase;
+    box-shadow:0 0 0 1px color-mix(in srgb, var(--signal) 55%, transparent), 0 10px 30px rgba(76,175,80,.28);
+    transition:transform .15s ease, box-shadow .25s ease, background .25s ease}
+  .btn:hover{background:var(--signal-hi);box-shadow:0 0 0 1px var(--signal), 0 14px 40px rgba(76,175,80,.42)}
+  .btn:active{transform:translateY(1px) scale(.99)}
+  .btn:focus-visible{outline:none;box-shadow:0 0 0 3px var(--bg), 0 0 0 5px var(--signal)}
+  .btn[disabled]{cursor:default;opacity:.7}
+  .btn::after{content:'';position:absolute;inset:0;transform:translateX(-130%);
+    background:linear-gradient(90deg, transparent, rgba(255,255,255,.38), transparent)}
+  .btn:not([disabled]):hover::after{animation:sheen .85s ease}
+  @keyframes sheen{to{transform:translateX(130%)}}
+
+  .telemetry{margin-top:18px;min-height:1.1em;
+    font-family:'JetBrains Mono',ui-monospace,monospace;
+    font-size:.7rem;letter-spacing:.12em;color:var(--mute)}
+  .foot{margin-top:34px;font-family:'JetBrains Mono',ui-monospace,monospace;
+    font-size:.6rem;letter-spacing:.3em;text-transform:uppercase;color:var(--mute);opacity:.65}
+
+  /* ── link-restored state ── */
+  body.online .strip i{opacity:1;background:var(--signal);box-shadow:var(--glow-signal)}
+  body.online .strip::before{display:none}
+  body.online .brand-dot,body.online .chip b{background:var(--signal);box-shadow:var(--glow-signal);animation:none}
+  body.online .chip{color:var(--signal);border-color:color-mix(in srgb, var(--signal) 45%, transparent)}
+  body.online .headline{animation:none}
+
+  @media (prefers-reduced-motion: reduce){
+    .panel>*,.headline{animation:none;opacity:1;transform:none}
+    .strip::before{display:none}.strip i{opacity:.5}
+    .brand-dot,.chip b{animation:none}.btn:hover::after{animation:none}
+  }
+</style>
+</head>
+<body>
+  <main class="panel" role="alert" aria-live="assertive">
+    <div class="brand"><span class="brand-dot" aria-hidden="true"></span><span class="brand-name">LED&nbsp;GRAB</span></div>
+    <div class="strip-wrap"><div class="strip" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i></div></div>
+    <p class="chip"><b aria-hidden="true"></b><span id="chip-text">No Signal</span></p>
+    <h1 class="headline"><span>Signal</span>Lost</h1>
+    <p class="copy">Can&rsquo;t reach the LED&nbsp;Grab server. Make sure it&rsquo;s running and your device is on the same network.</p>
+    <button id="retry" class="btn" type="button"><span id="btn-label">Reconnect</span></button>
+    <p class="telemetry" id="telemetry" aria-live="polite">Listening for the server&hellip;</p>
+    <p class="foot">LED&nbsp;Grab &middot; Local Console</p>
+  </main>
+  <script>
+  (function(){
+    var RETRY = 3; // seconds between automatic probes
+    var attempts = 0, checking = false, done = false, timer = null;
+    var tel = document.getElementById('telemetry');
+    var chipText = document.getElementById('chip-text');
+    var btn = document.getElementById('retry');
+    var btnLabel = document.getElementById('btn-label');
+
+    function pad(n){ return n < 10 ? '0' + n : '' + n; }
+    function say(m){ if (tel) tel.textContent = m; }
+
+    function probe(){
+      if (checking || done) return;
+      checking = true; attempts++;
+      if (btn) btn.disabled = true;
+      if (btnLabel) btnLabel.textContent = 'Checking';
+      say('Probing for signal · attempt ' + pad(attempts));
+      // Any settled response (even 401/403) means the server is reachable.
+      // Cache-bust + no-store so a stale SW cache can't fake a recovery.
+      fetch('/?_swping=' + Date.now(), { method: 'HEAD', cache: 'no-store' })
+        .then(restored)
+        .catch(function(){
+          checking = false;
+          if (btn) btn.disabled = false;
+          if (btnLabel) btnLabel.textContent = 'Reconnect';
+          countdown(RETRY);
+        });
+    }
+
+    function restored(){
+      done = true;
+      document.body.classList.add('online');
+      if (chipText) chipText.textContent = 'Link Restored';
+      if (btnLabel) btnLabel.textContent = 'Reconnecting';
+      say('Signal acquired — reloading');
+      setTimeout(function(){ location.reload(); }, 750);
+    }
+
+    function countdown(s){
+      if (done) return;
+      if (s <= 0){ probe(); return; }
+      say('Retrying in ' + pad(s) + 's · attempt ' + pad(attempts + 1));
+      timer = setTimeout(function(){ countdown(s - 1); }, 1000);
+    }
+
+    function probeNow(){ if (timer){ clearTimeout(timer); timer = null; } probe(); }
+
+    if (btn) btn.addEventListener('click', probeNow);
+    window.addEventListener('online', probeNow);
+    document.addEventListener('visibilitychange', function(){ if (!document.hidden) probeNow(); });
+
+    probe();
+  })();
+  </script>
+</body>
+</html>`;
+
 // Install: pre-cache core shell
 self.addEventListener('install', (event) => {
     event.waitUntil(
@@ -66,17 +279,17 @@ self.addEventListener('fetch', (event) => {
         return;
     }
 
-    // Navigation: network-only (page requires auth, no useful offline fallback)
+    // Navigation: network-first with branded, self-healing offline fallback
     if (event.request.mode === 'navigate') {
         event.respondWith(
             fetch(event.request).catch(() =>
-                new Response(
+                new Response(OFFLINE_HTML, {
-                    '<html><body style="font-family:system-ui;text-align:center;padding:60px 20px;background:#1a1a1a;color:#ccc">' +
+                    status: 503,
-                    '<h2>LED Grab</h2><p>Cannot reach the server. Check that it is running and you are on the same network.</p>' +
+                    headers: {
-                    '<button onclick="location.reload()" style="margin-top:20px;padding:10px 24px;border-radius:8px;border:none;background:#4CAF50;color:#fff;font-size:1rem;cursor:pointer">Retry</button>' +
+                        'Content-Type': 'text/html; charset=utf-8',
-                    '</body></html>',
+                        'Cache-Control': 'no-store',
-                    { status: 503, headers: { 'Content-Type': 'text/html' } }
+                    },
-                )
+                })
             )
         );
         return;

server/src/ledgrab/storage/automation.py

@@ -30,11 +30,24 @@ class Rule:
 
 @dataclass
 class ApplicationRule(Rule):
-    """Activate when specified applications are running or topmost."""
+    """Activate when specified applications are running or topmost.
+
+    ``apps`` values are platform-specific and NOT portable across OSes:
+    on Windows they are **process names** (e.g. ``chrome.exe``); on Android
+    they are **package names** (e.g. ``com.android.chrome``). Matching is
+    exact and case-insensitive. The automation editor sources values from the
+    right place per platform (running processes on desktop, launchable apps on
+    Android), so a rule authored on one OS will simply not match on another.
+
+    ``match_type`` is honoured on Windows for all four values below. On Android
+    only the foreground app is obtainable, so every match type collapses to
+    "this app is in the foreground" and the editor hides the selector.
+    """
 
     rule_type: str = "application"
     apps: List[str] = field(default_factory=list)
-    match_type: str = "running"  # "running" | "topmost"
+    # "running" | "topmost" | "fullscreen" | "topmost_fullscreen"
+    match_type: str = "running"
 
     def to_dict(self) -> dict:
         d = super().to_dict()

server/src/ledgrab/storage/base_sqlite_store.py

@@ -6,7 +6,10 @@ writes go through to SQLite immediately (write-through cache).
 """
 
 import asyncio
+import copy
 import threading
+import uuid
+from datetime import datetime, timezone
 from typing import Callable, Dict, Generic, List, TypeVar
 
 from ledgrab.storage.database import Database
@@ -26,6 +29,10 @@ class BaseSqliteStore(Generic[T]):
 
     _table_name: str
     _entity_name: str
+    # Opt-in allowlist for clone(): defaults off so a new (possibly
+    # secret-bearing) store is never cloneable by accident. Subclasses that hold
+    # no inline secrets and are safe to duplicate set this True.
+    _cloneable: bool = False
 
     def __init__(self, db: Database, deserializer: Callable[[dict], T]):
         self._db = db
@@ -136,13 +143,50 @@ class BaseSqliteStore(Generic[T]):
             await asyncio.to_thread(self._delete_item, item_id)
         logger.info(f"Deleted {self._entity_name}: {item_id}")
 
+    def clone(self, item_id: str, new_name: str) -> T:
+        """Faithfully duplicate an entity under a new id and name.
+
+        Deep-copies every field of the original (no serialize/deserialize
+        round-trip, so no field can be silently lost to a schema/dataclass name
+        mismatch), mints a fresh id that preserves the original's id prefix,
+        applies ``new_name`` and resets timestamps. References *inside* the clone
+        still point at whatever the original referenced — callers that want to
+        rewire intra-set references must do so after cloning.
+
+        SECURITY: this copies *every* field verbatim, including any secret a
+        model might hold. Callers must restrict cloning to non-secret-bearing
+        kinds (see ``_DUPLICABLE_KINDS`` in ``api/routes/graph.py``).
+        """
+        if not self._cloneable:
+            raise NotImplementedError(f"{self._entity_name} store does not support cloning")
+        with self._lock:
+            if item_id not in self._items:
+                from ledgrab.storage.base_store import EntityNotFoundError
+
+                raise EntityNotFoundError(f"{self._entity_name} not found: {item_id}")
+            self._check_name_unique(new_name)
+            new = copy.deepcopy(self._items[item_id])
+            prefix = item_id.rsplit("_", 1)[0] if "_" in item_id else item_id
+            new_id = f"{prefix}_{uuid.uuid4().hex[:8]}"
+            now = datetime.now(timezone.utc)
+            new.id = new_id
+            new.name = new_name
+            if hasattr(new, "created_at"):
+                new.created_at = now
+            if hasattr(new, "updated_at"):
+                new.updated_at = now
+            self._items[new_id] = new
+            self._save_item(new_id, new)
+        logger.info("Cloned %s %s -> %s (%s)", self._entity_name, item_id, new_id, new_name)
+        return new
+
     def count(self) -> int:
         with self._lock:
             return len(self._items)
 
     # -- Helpers -------------------------------------------------------------
 
-    def _check_name_unique(self, name: str, exclude_id: str = None) -> None:
+    def _check_name_unique(self, name: str, exclude_id: str | None = None) -> None:
         """Raise ValueError if *name* is empty or already taken.
 
         Must be called while holding ``self._lock``.

server/src/ledgrab/storage/color_strip_store.py

@@ -33,6 +33,7 @@ class ColorStripStore(BaseSqliteStore[ColorStripSource]):
 
     _table_name = "color_strip_sources"
     _entity_name = "Color strip source"
+    _cloneable = True  # no inline secrets — only references shared entities by id
 
     def __init__(self, db: Database):
         super().__init__(db, ColorStripSource.from_dict)