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).

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
-- Adalight (serial) — Arduino-compatible LED controllers
-- AmbileD (serial)
-- DDP (Distributed Display Protocol, UDP)
-- OpenRGB — PC peripherals (keyboard, mouse, RAM, fans, LED strips)
-- Serial port auto-detection and baud rate configuration
+LedGrab speaks many protocols, so a single setup can drive everything from a DIY strip to off-the-shelf smart bulbs:
+
+![Device type picker](docs/screenshots/devices.PNG)
+
+- **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 / 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.)
-- Dynamic brightness value sources (schedule-based, scene-aware)
-- Key Colors (KC) targets with live WebSocket color streaming
+- Automations engine with condition-based rules — switch targets, scenes, or brightness by time of day, active window/process, MQTT, webhooks, or game events
+- Scene presets for one-click lighting changes
+- 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
-- Windows, Linux, or macOS — all core features work cross-platform
-
-### 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 |
+- A supported LED device on the local network, connected via USB/serial, or reachable over Bluetooth
+- Windows, Linux, or macOS
 
 ## 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.
-
-## 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
-```
+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.
 
 ## Configuration
 
@@ -187,14 +196,15 @@ server:
   host: "0.0.0.0"
   port: 8080
   log_level: "INFO"
+  cors_origins:
+    - "http://localhost:8080"
 
 auth:
-  api_keys:
-    dev: "development-key-change-in-production"
-
-storage:
-  devices_file: "data/devices.json"
-  templates_file: "data/capture_templates.json"
+  # Empty (default) → loopback-only anonymous access; LAN requests are rejected.
+  # Add a key to enable LAN/remote access (generate one with: openssl rand -hex 32).
+  api_keys: {}
+  # api_keys:
+  #   dev: "your-secret-key-here"
 
 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
-- **Picture Sources** — Screen capture stream definitions
-- **Picture Targets** — LED target management, start/stop processing
-- **Post-Processing Templates** — Filter pipeline configurations
-- **Color Strip Sources** — Audio, pattern, composite, mapped sources
-- **Audio Sources** — Multichannel and mono audio device configuration
-- **Pattern Templates** — Effect pattern definitions
-- **Value Sources** — Dynamic brightness/value providers
-- **Key Colors Targets** — KC targets with WebSocket live color stream
-- **Profiles** — Condition-based automation profiles
+- **Capture Templates** & **Picture Sources** — screen capture configuration and stream definitions
+- **Output Targets** — LED target management, start/stop processing, live color stream
+- **Post-Processing Templates** — filter pipeline configurations
+- **Color Strip Sources**, **Pattern Templates**, **Gradients** — color generation
+- **Audio Sources / Templates / Filters** — audio capture and reactive processing
+- **Value Sources**, **Weather Sources**, **Scene Presets** — dynamic parameters and presets
+- **Automations**, **Webhooks**, **HTTP Endpoints**, **Game Integration** — triggers and rules
+- **MQTT** & **Home Assistant** — broker sources and HA integration
 
-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 ".[camera]"   # Webcam capture via OpenCV
+pip install -e ".[perf]"            # High-performance capture engines (Windows: DXCam, BetterCam, WGC)
+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).
-
-## 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
+MIT — see [LICENSE](LICENSE). Free and open source.

TODO.md

@@ -993,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/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
-        // been recreated; ensureRunningPanelInflated already keys off
-        // the field reference.
-        if (CaptureService.isRunning && ::stoppedPanel.isInitialized) {
+        // service is still running. The running panel's view may have been
+        // recreated; ensureRunningPanelInflated already keys off the field
+        // reference. When stopped, refresh the notification-access button —
+        // 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/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`
-**API Version:** v1
+- **Base URL:** `http://localhost:8080`
+- **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)
-- [Device Management](#device-management)
-- [Processing Control](#processing-control)
-- [Settings Management](#settings-management)
-- [Calibration](#calibration)
-- [Metrics](#metrics)
+- [Authentication](#authentication)
+- [Conventions](#conventions)
+- [WebSocket protocol](#websocket-protocol)
+- [Worked examples](#worked-examples)
+- **Endpoint reference**
+  - [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",
-  "version": "0.1.0"
+  "timestamp": "2026-05-29T12:00:00Z",
+  "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
-{
-  "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"
-}
+{ "status": "started", "target_id": "ot_abc123" }
 ```
 
-### GET /api/v1/devices
+**Authenticated request with a configured key:**
 
-List all attached devices.
-
-**Response:**
-```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": []
-}
+```bash
+curl -H "Authorization: Bearer your-api-key" \
+  http://localhost:8080/api/v1/devices
 ```
 
 ---
 
-## 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:**
-```json
-{
-  "display_index": 0,
-  "fps": 30,
-  "brightness": 1.0,
-  "smoothing": 0.3,
-  "interpolation_mode": "average",
-  "standby_interval": 1.0,
-  "state_check_interval": 30
-}
-```
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/health` | Service health: status, version, uptime, and whether auth/setup is required. |
+| GET | `/api/v1/version` | Application version, Python version, and API version. |
+| GET | `/api/v1/tags` | All tags used across every entity in the system. |
+| GET | `/api/v1/config/displays` | Available displays/monitors for screen capture (optional `engine_type` query, e.g. `scrcpy`). |
+| GET | `/api/v1/system/processes` | Running process names, for use in automation conditions. |
+| GET | `/api/v1/system/performance` | Current CPU, RAM, and GPU utilization metrics. |
+| GET | `/api/v1/system/metrics-history` | Last ~2 minutes of system and per-target metrics for dashboard charts. |
+| 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:**
-```json
-{
-  "display_index": 1,
-  "fps": 60,
-  "brightness": 0.8
-}
-```
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/v1/system/mqtt/settings` | Current MQTT broker settings (password masked). |
+| PUT | `/api/v1/system/mqtt/settings` | Update MQTT broker settings (empty password preserves existing). |
+| GET | `/api/v1/system/external-url` | Configured external base URL. |
+| 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
-
-Get calibration configuration.
-
-**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
+- [Installation Guide](../INSTALLATION.md)
+- [Calibration Guide](CALIBRATION.md)
+- Interactive, always-current schemas: [`/docs`](http://localhost:8080/docs)

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`
-- Env var: `LEDGRAB_AUTH__API_KEYS`
-- When `api_keys` is empty (default), auth is disabled — all endpoints are open
-- To enable auth, add key entries (e.g. `dev: "your-secret-key"`)
+- Config: `config/default_config.yaml` under `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 **set**: a valid Bearer token is required from every client (loopback included).
+- `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/src/ledgrab/api/graph_schema.py

@@ -99,6 +99,8 @@ CONNECTION_SCHEMA: tuple[ConnectionField, ...] = (
     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"),
@@ -129,6 +131,11 @@ CONNECTION_SCHEMA: tuple[ConnectionField, ...] = (
         )
     ),
     # ── 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",
@@ -168,7 +175,6 @@ CONNECTION_SCHEMA: tuple[ConnectionField, ...] = (
     # ── Output targets ──
     ConnectionField("output_target", "device_id", "device", "device"),
     ConnectionField("output_target", "color_strip_source_id", "color_strip_source", "colorstrip"),
-    ConnectionField("output_target", "picture_source_id", "picture_source", "picture"),
     ConnectionField(
         "output_target", "brightness.source_id", "value_source", "value", bindable=True, nested=True
     ),
@@ -201,6 +207,34 @@ def schema_for_kind(kind: str) -> list[ConnectionField]:
     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 [
@@ -212,6 +246,7 @@ def schema_as_dicts() -> list[dict[str, Any]]:
             "bindable": c.bindable,
             "nested": c.nested,
             "is_list": c.is_list,
+            "editable": is_editable(c),
         }
         for c in CONNECTION_SCHEMA
     ]
@@ -244,6 +279,54 @@ def extract_refs(entity: dict[str, Any], field_path: str) -> list[str]:
     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.
 
@@ -269,6 +352,32 @@ def serialize_entity(model: Any) -> dict[str, Any]:
     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 ───────────────────────────────────────────────────
 
 
@@ -480,12 +589,11 @@ def validate_connection(
     )
     if cf is None:
         return False, f"Unknown connection field: {target_kind}.{field}"
-    if cf.is_list:
-        # List slots (layers/zones/scene targets) hold many edges sharing the
-        # same (to, field); without an element index this endpoint can't model
-        # which one is being replaced for the cycle check. Edit those via the
-        # entity editor.
-        return False, f"List connection '{field}' must be edited via the entity editor"
+    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:

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

@@ -26,9 +26,13 @@ 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,
 )
 
@@ -78,7 +82,7 @@ def _gather_entities() -> dict[str, list[dict[str, Any]]]:
             logger.warning("graph: store for kind %s unavailable: %s", kind, exc)
             out[kind] = []
             continue
-        out[kind] = [serialize_entity(m) for m in models]
+        out[kind] = [serialize_entity_for_graph(kind, m) for m in models]
     return out
 
 
@@ -122,3 +126,124 @@ async def validate_graph_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

@@ -70,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 "",
@@ -302,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":
@@ -464,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
@@ -476,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

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:
-                    msg["raw_value"] = round(raw, 4)
-                    if hasattr(stream, "_min_ha"):
-                        msg["raw_range"] = [stream._min_ha, stream._max_ha]
+                if isinstance(raw, bool):
+                    # bool is a subclass of int — send as-is (don't coerce/round).
+                    msg["raw_value"] = raw
+                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/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."""
 
@@ -215,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.
 
@@ -222,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()
 
@@ -276,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)
 
@@ -369,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/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
-        for backend_cls in (_WindowsBackend, _LinuxBackend):
+        # Try platform backends in order (Android first — it reports platform.system()
+        # == "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]
-        ha_range = self._max_ha - self._min_ha
-        if abs(ha_range) < 1e-9:
-            normalized = 0.5
+        if self._normalize_enabled:
+            # Normalize to [0, 1] via the configured min/max range.
+            ha_range = self._max_ha - self._min_ha
+            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
+        # EMA smoothing — both branches produce a [0, 1] value, so _prev_value
+        # is always normalized and flipping ``normalize`` live never blends a
+        # 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 abs(rng) < 1e-9:
-            normalized = 0.5
+        if self._normalize_enabled:
+            rng = self._max_value - self._min_value
+            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
-        normalized = max(0.0, min(1.0, normalized))
+            # Skip the rescale: treat the extracted number as already a 0–1
+            # 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
-        normalized = self._normalize(raw)
+        if self._normalize_enabled:
+            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)
-        stream.start()
+        # Increment around create+start: a referencing stream (template /
+        # 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/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/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, graphShowIssues, graphExportTopology,
+    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,
 
@@ -627,6 +631,7 @@ Object.assign(window, {
     graphRelayout,
     graphShowIssues,
     graphExportTopology,
+    graphDuplicateSelection,
     graphToggleFullscreen,
     graphAddEntity,
     toggleToolbarOverflow,

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

@@ -8,6 +8,7 @@ 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 {
@@ -62,6 +63,69 @@ export async function getDependents(kind: string, id: string): Promise<GraphDepe
     }
 }
 
+/* ── 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 ────────────────────────────────────────────────────── */
 
 interface ConnectionEntry {
@@ -112,17 +176,24 @@ 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, 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 },
@@ -206,6 +277,25 @@ export function getConnectionByField(targetKind: string, field: string): Connect
     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
@@ -226,6 +316,21 @@ export async function updateConnection(targetId: string, targetKind: string, fie
         ? { [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);
         // Invalidate the relevant cache so data refreshes
@@ -243,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;
@@ -124,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');

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

@@ -29,6 +29,10 @@ 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 {
@@ -236,7 +240,7 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         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) return;
         // The referrer (`to`) is always a current entity in these loops; if the
         // referenced entity (`from`) is missing, the reference is dangling —
@@ -254,7 +258,7 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         );
         // 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
@@ -348,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
@@ -360,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) {
-                if (layer.source_id) addEdge(layer.source_id, s.id, 'layer.source_id');
+            s.layers.forEach((layer: any, i: number) => {
+                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) {
-                if (zone.source_id) addEdge(zone.source_id, s.id, 'zone.source_id');
-            }
+            s.zones.forEach((zone: any, i: number) => {
+                if (zone.source_id) addEdge(zone.source_id, s.id, 'zone.source_id', '', { list: 'zones', index: i, ref: 'source_id' });
+            });
         }
 
         // Advanced picture calibration lines
@@ -405,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');

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

@@ -106,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 },
@@ -656,7 +657,7 @@ export function markIssues(group: SVGGElement, issues: Map<string, string[]>): v
 
     for (const [id, msgs] of issues) {
         if (!msgs.length) continue;
-        const el = group.querySelector(`.graph-node[data-id="${id}"]`);
+        const el = group.querySelector(`.graph-node[data-id="${CSS.escape(id)}"]`);
         if (!el) continue;
         el.classList.add('has-issue');
 

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
- * a textarea).
+ * Items may be plain strings (display == stored value) or `{ value, label }`
+ * 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 {
-    name: string;
+/** An item with a display label distinct from its stored value. */
+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(
-                opts.textarea.value.split('\n').map(s => s.trim().toLowerCase()).filter(Boolean),
-            );
+            this._existing = this._textareaValues(opts.textarea);
             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._multiTextarea!.value.split('\n').map(s => s.trim().toLowerCase()).filter(Boolean),
-            );
+            this._existing = this._textareaValues(this._multiTextarea!);
         }
 
         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))
-            .map(p => ({
-                name: p,
-                added: this._existing.has(p.toLowerCase()),
-            }));
+            .filter(p => !q || p.label.toLowerCase().includes(q) || p.value.toLowerCase().includes(q))
+            .map(p => ({ ...p, added: this._existing.has(p.value.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
-                    ? t('automations.condition.application.no_processes')
-                    : '—'
+                this._items.length === 0 ? t(this._emptyKey) : '—'
             }</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>
-                ${item.added ? '<span class="ep-item-desc">\u2713</span>' : ''}
+                <span class="ep-item-label">${escapeHtml(item.label)}</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;
-                this._existing.add(item.name.toLowerCase());
+                ta.value = cur ? cur + '\n' + item.value : item.value;
+                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/graph-editor.ts

@@ -19,7 +19,7 @@ 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, validateConnection, getDependents } 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, writeJson, isObject, isString, isNumber } from '../core/storage.ts';
@@ -358,6 +358,10 @@ 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();
         // Index raw entities by id for subtype-safe bindable-slot resolution.
@@ -805,6 +809,40 @@ export async function graphExportTopology(): Promise<void> {
     }
 }
 
+/**
+ * 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) {
@@ -1353,6 +1391,10 @@ function _graphHTML(): string {
                     <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>
@@ -2628,16 +2670,22 @@ function _onConnectPointerUp(e: PointerEvent): void {
 }
 
 /**
- * Keep only the bindable slots the target entity actually exposes (subtype-safe)
- * — e.g. an "effect" strip offers `intensity`/`scale`, a "picture" strip offers
- * `smoothing`. Non-bindable matches always pass through.
+ * 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; bindable?: boolean }>(matches: T[], targetId: string): T[] {
+function _availableMatches<T extends { field: string }>(matches: T[], targetId: string): T[] {
     const ent = _entitiesById.get(targetId);
-    return matches.filter(m => {
-        if (!m.bindable || !ent) return true;
-        return m.field.split('.')[0] in ent;
-    });
+    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. */
@@ -2841,6 +2889,13 @@ function _onEdgeContextMenu(edgePath: Element, e: MouseEvent, container: HTMLEle
     _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') ?? '';
@@ -2877,6 +2932,73 @@ function _dismissEdgeContextMenu(): void {
     }
 }
 
+/**
+ * Re-wire menu for a list-slot edge (a composite layer or mapped zone source).
+ * Each such edge carries `data-slot-*`, so we can replace just that one
+ * 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 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) {
+        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.connection_failed'), 'error');
+    }
+}
+
 async function _detachSelectedEdge(): Promise<void> {
     if (!_selectedEdge) return;
     const { from, to, field, targetKind } = _selectedEdge;

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;
 
@@ -379,6 +381,7 @@ startTargetOverlay: (...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",
@@ -1225,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:",
@@ -1985,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.",
@@ -2072,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",
@@ -2590,7 +2601,10 @@
   "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}",
@@ -2601,6 +2615,12 @@
   "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",
@@ -3064,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": "Нет дополнительных настроек",
@@ -1259,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": "Время начала:",
@@ -1845,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). Делает переходы рассвета и заката круче или плавнее.",
@@ -1932,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",
@@ -2272,7 +2283,10 @@
   "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}",
@@ -2283,6 +2297,12 @@
   "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": "Автоматизация выключена",
@@ -2746,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": "无额外配置",
@@ -1255,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": "开始时间：",
@@ -1841,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）。使日出/日落过渡更陡峭或更平缓。",
@@ -1928,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",
@@ -2268,7 +2279,10 @@
   "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}",
@@ -2279,6 +2293,12 @@
   "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": "自动化已禁用",
@@ -2740,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/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)

server/src/ledgrab/storage/output_target_store.py

@@ -95,6 +95,8 @@ class OutputTargetStore(BaseSqliteStore[OutputTarget]):
         min_brightness_threshold: Any = 0,
         adaptive_fps: bool = False,
         protocol: str = "ddp",
+        max_milliamps: int = 0,
+        milliamps_per_led: int = 55,
         description: str | None = None,
         tags: List[str] | None = None,
         # legacy compat
@@ -116,6 +118,8 @@ class OutputTargetStore(BaseSqliteStore[OutputTarget]):
             min_brightness_threshold=BindableFloat.from_raw(min_brightness_threshold, default=0.0),
             adaptive_fps=adaptive_fps,
             protocol=protocol,
+            max_milliamps=max(0, int(max_milliamps or 0)),
+            milliamps_per_led=max(1, int(milliamps_per_led or 55)),
             description=description,
             created_at=now,
             updated_at=now,
@@ -335,6 +339,8 @@ class OutputTargetStore(BaseSqliteStore[OutputTarget]):
         min_brightness_threshold: Any = None,
         adaptive_fps: bool | None = None,
         protocol: str | None = None,
+        max_milliamps: int | None = None,
+        milliamps_per_led: int | None = None,
         description: str | None = None,
         tags: List[str] | None = None,
         icon: str | None = None,
@@ -356,6 +362,8 @@ class OutputTargetStore(BaseSqliteStore[OutputTarget]):
             min_brightness_threshold=min_brightness_threshold,
             adaptive_fps=adaptive_fps,
             protocol=protocol,
+            max_milliamps=max_milliamps,
+            milliamps_per_led=milliamps_per_led,
             description=description,
             tags=tags,
             icon=icon,

server/src/ledgrab/storage/value_source.py

@@ -66,6 +66,11 @@ class ValueSource:
             "use_real_time": None,
             "latitude": None,
             "longitude": None,
+            # Template (Jinja expression combinator)
+            "template": None,
+            "inputs": None,
+            "default_value": None,
+            "eval_interval": None,
         }
         if self.icon:
             d["icon"] = self.icon
@@ -391,6 +396,11 @@ class HAEntityValueSource(ValueSource):
     min_ha_value: float = 0.0  # raw HA value mapped to output 0.0
     max_ha_value: float = 100.0  # raw HA value mapped to output 1.0
     smoothing: float = 0.0  # EMA smoothing factor (0.0–1.0)
+    # When False, skip the min/max rescale: get_value() clamps the raw value
+    # into [0,1] as-is (for entities that already report a 0–1 fraction). The
+    # un-clamped magnitude stays available via get_raw_value(). get_value() is
+    # always in [0,1] regardless, so the normalized scalar bus is preserved.
+    normalize: bool = True
 
     def to_dict(self) -> dict:
         d = super().to_dict()
@@ -400,6 +410,7 @@ class HAEntityValueSource(ValueSource):
         d["min_ha_value"] = self.min_ha_value
         d["max_ha_value"] = self.max_ha_value
         d["smoothing"] = self.smoothing
+        d["normalize"] = self.normalize
         return d
 
     @classmethod
@@ -416,6 +427,7 @@ class HAEntityValueSource(ValueSource):
                 data.get("max_ha_value") if data.get("max_ha_value") is not None else 100.0
             ),
             smoothing=float(data.get("smoothing") or 0.0),
+            normalize=bool(data.get("normalize", True)),
         )
 
 
@@ -514,6 +526,13 @@ class GameEventValueSource(ValueSource):
     smoothing: float = 0.0  # EMA smoothing factor (0.0-1.0)
     default_value: float = 0.5  # value when timed out or no events
     timeout: float = 5.0  # seconds before reverting to default
+    # When False, skip the min/max rescale: get_value() clamps the raw game
+    # value into [0,1] as-is. The un-clamped value stays available via
+    # get_raw_value(). get_value() is always in [0,1]. See HAEntityValueSource.
+    # NOTE: game_event has no value-source CRUD schema/API (constructed only via
+    # the game-integration path), so this flag is settable only there, not over
+    # POST/PUT /value-sources.
+    normalize: bool = True
 
     def to_dict(self) -> dict:
         d = super().to_dict()
@@ -524,6 +543,7 @@ class GameEventValueSource(ValueSource):
         d["smoothing"] = self.smoothing
         d["default_value"] = self.default_value
         d["timeout"] = self.timeout
+        d["normalize"] = self.normalize
         return d
 
     @classmethod
@@ -543,6 +563,7 @@ class GameEventValueSource(ValueSource):
                 data.get("default_value") if data.get("default_value") is not None else 0.5
             ),
             timeout=float(data.get("timeout") if data.get("timeout") is not None else 5.0),
+            normalize=bool(data.get("normalize", True)),
         )
 
 
@@ -562,6 +583,10 @@ class SystemMetricsValueSource(ValueSource):
     sensor_label: str = ""  # for cpu_temp/fan_speed (empty = first available)
     poll_interval: float = 1.0  # seconds between reads
     smoothing: float = 0.0  # EMA smoothing factor
+    # When False, skip the min/max rescale: get_value() clamps the raw metric
+    # into [0,1] as-is. The un-clamped reading stays available via
+    # get_raw_value(). get_value() is always in [0,1]. See HAEntityValueSource.
+    normalize: bool = True
 
     def to_dict(self) -> dict:
         d = super().to_dict()
@@ -573,6 +598,7 @@ class SystemMetricsValueSource(ValueSource):
         d["sensor_label"] = self.sensor_label
         d["poll_interval"] = self.poll_interval
         d["smoothing"] = self.smoothing
+        d["normalize"] = self.normalize
         return d
 
     @classmethod
@@ -591,6 +617,7 @@ class SystemMetricsValueSource(ValueSource):
             sensor_label=data.get("sensor_label") or "",
             poll_interval=float(data.get("poll_interval") or 1.0),
             smoothing=float(data.get("smoothing") or 0.0),
+            normalize=bool(data.get("normalize", True)),
         )
 
 
@@ -617,6 +644,11 @@ class HTTPValueSource(ValueSource):
     min_value: float = 0.0  # raw value → 0.0
     max_value: float = 100.0  # raw value → 1.0
     smoothing: float = 0.0  # EMA smoothing on the normalized output
+    # When False, skip the min/max rescale: get_value() coerces the extracted
+    # value to float and clamps it into [0,1] as-is. The verbatim extracted
+    # value (which may be str/bool) stays available via get_raw_value().
+    # get_value() is always a float in [0,1]. See HAEntityValueSource.
+    normalize: bool = True
 
     def to_dict(self) -> dict:
         d = super().to_dict()
@@ -626,6 +658,7 @@ class HTTPValueSource(ValueSource):
         d["min_value"] = self.min_value
         d["max_value"] = self.max_value
         d["smoothing"] = self.smoothing
+        d["normalize"] = self.normalize
         return d
 
     @classmethod
@@ -640,6 +673,70 @@ class HTTPValueSource(ValueSource):
             min_value=float(data.get("min_value") or 0.0),
             max_value=float(data.get("max_value") if data.get("max_value") is not None else 100.0),
             smoothing=float(data.get("smoothing") or 0.0),
+            normalize=bool(data.get("normalize", True)),
+        )
+
+
+def _coerce_float(value, fallback):
+    """Best-effort float; returns ``fallback`` on None/non-numeric.
+
+    Keeps a tampered DB / buggy migration from dropping the whole row when
+    BaseSqliteStore's loader swallows a per-row deserialization error.
+    """
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return fallback
+
+
+@dataclass
+class TemplateValueSource(ValueSource):
+    """Value source that evaluates a sandboxed Jinja expression over the live
+    values of other value sources (the system's float combinator).
+
+    ``template`` is a Jinja *expression* (no statements/blocks) evaluated by the
+    hardened engine in :mod:`ledgrab.utils.template_expr`. Each entry in
+    ``inputs`` binds a variable ``name`` to another value source by id; at
+    runtime the variable holds that source's normalized ``get_value()`` (0..1)
+    and ``raw[name]`` holds its un-normalized ``get_raw_value()`` (float) where
+    the stream exposes one. The callables ``min``/``max``/``abs``/``round``/
+    ``clamp`` are available. The result is coerced to float, NaN/inf rejected,
+    and clamped to [0, 1]; any error falls back to ``default_value``.
+    """
+
+    template: str = ""
+    inputs: List[dict] = field(default_factory=list)  # [{name, value_source_id}]
+    default_value: float = 0.0  # fallback when the expression errors (0.0-1.0)
+    eval_interval: float | None = None  # re-eval throttle (s); None/0 = every poll
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["template"] = self.template
+        d["inputs"] = [dict(i) for i in self.inputs]
+        d["default_value"] = self.default_value
+        d["eval_interval"] = self.eval_interval
+        d["return_type"] = "float"
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "TemplateValueSource":
+        common = _parse_common_fields(data)
+        raw_inputs = data.get("inputs") or []
+        inputs = [
+            {
+                "name": str(i.get("name", "")),
+                "value_source_id": str(i.get("value_source_id", "")),
+            }
+            for i in raw_inputs
+            if isinstance(i, dict)
+        ]
+        return cls(
+            **common,
+            source_type="template",
+            template=data.get("template") or "",
+            inputs=inputs,
+            default_value=_coerce_float(data.get("default_value"), 0.0),
+            eval_interval=_coerce_float(data.get("eval_interval"), None),
         )
 
 
@@ -661,4 +758,5 @@ _VALUE_SOURCE_MAP: Dict[str, Type[ValueSource]] = {
     "system_metrics": SystemMetricsValueSource,
     "game_event": GameEventValueSource,
     "http": HTTPValueSource,
+    "template": TemplateValueSource,
 }

server/src/ledgrab/storage/value_source_factories.py

@@ -40,6 +40,7 @@ from ledgrab.storage.value_source import (
     StaticColorValueSource,
     StaticValueSource,
     SystemMetricsValueSource,
+    TemplateValueSource,
     ValueSource,
     _VALUE_SOURCE_MAP,
 )
@@ -237,6 +238,7 @@ def _build_ha_entity(
     min_ha_value: float | None = None,
     max_ha_value: float | None = None,
     smoothing: float | None = None,
+    normalize: bool | None = None,
     **_,
 ) -> ValueSource:
     if not ha_source_id:
@@ -251,6 +253,7 @@ def _build_ha_entity(
         min_ha_value=min_ha_value if min_ha_value is not None else 0.0,
         max_ha_value=max_ha_value if max_ha_value is not None else 100.0,
         smoothing=smoothing if smoothing is not None else 0.0,
+        normalize=normalize if normalize is not None else True,
     )
 
 
@@ -301,6 +304,7 @@ def _build_system_metrics(
     sensor_label: str | None = None,
     poll_interval: float | None = None,
     smoothing: float | None = None,
+    normalize: bool | None = None,
     **_,
 ) -> ValueSource:
     m = metric or "cpu_load"
@@ -316,6 +320,7 @@ def _build_system_metrics(
         sensor_label=sensor_label or "",
         poll_interval=poll_interval if poll_interval is not None else 1.0,
         smoothing=smoothing if smoothing is not None else 0.0,
+        normalize=normalize if normalize is not None else True,
     )
 
 
@@ -347,6 +352,7 @@ def _build_http(
     min_value: float | None = None,
     max_value: float | None = None,
     smoothing: float | None = None,
+    normalize: bool | None = None,
     **_,
 ) -> ValueSource:
     if not http_endpoint_id:
@@ -362,6 +368,80 @@ def _build_http(
         min_value=min_value if min_value is not None else 0.0,
         max_value=max_value if max_value is not None else 100.0,
         smoothing=smoothing if smoothing is not None else 0.0,
+        normalize=normalize if normalize is not None else True,
+    )
+
+
+def _validate_template_inputs(inputs: list | None) -> list:
+    """Validate + normalize template input bindings.
+
+    Each input is ``{name, value_source_id}``; ``name`` must be a valid,
+    non-reserved identifier and unique. ``value_source_id`` is *not* required to
+    resolve (lenient, like gradient_map) — a missing/unknown id just yields a
+    runtime fallback to ``default_value``.
+    """
+    from ledgrab.utils.template_expr import validate_input_name
+
+    result: list = []
+    seen: set = set()
+    for item in inputs or []:
+        if not isinstance(item, dict):
+            raise ValueError("each template input must be an object with name and value_source_id")
+        name = str(item.get("name", "")).strip()
+        vs_id = str(item.get("value_source_id", "")).strip()
+        validate_input_name(name)  # identifier + reserved-name check (raises ValueError)
+        if name in seen:
+            raise ValueError(f"duplicate template input name: {name!r}")
+        seen.add(name)
+        result.append({"name": name, "value_source_id": vs_id})
+    return result
+
+
+def _reject_unbound_template_vars(template: str, inputs: list) -> None:
+    """Reject expression variables that aren't bound to an input.
+
+    An unbound variable raises ``UndefinedError`` at runtime, so the template
+    would silently always return ``default_value`` — almost always a typo. The
+    globals (min/max/abs/round/clamp) and ``raw`` are excluded by
+    ``extract_variables``, so anything left over is genuinely unbound.
+    """
+    from ledgrab.utils.template_expr import extract_variables
+
+    declared = {i["name"] for i in inputs}
+    undeclared = sorted(set(extract_variables(template)) - declared)
+    if undeclared:
+        raise ValueError("expression uses unbound variable(s): " + ", ".join(undeclared))
+
+
+def _build_template(
+    *,
+    common: dict,
+    template: str | None = None,
+    inputs: list | None = None,
+    default_value: float | None = None,
+    eval_interval: float | None = None,
+    **_,
+) -> ValueSource:
+    from ledgrab.utils.template_expr import validate_template_expression
+
+    tpl = (template or "").strip()
+    if not tpl:
+        raise ValueError("template expression is required for template type")
+    validate_template_expression(tpl)  # raises ValueError on compile / cost-bomb
+    clean_inputs = _validate_template_inputs(inputs)
+    _reject_unbound_template_vars(tpl, clean_inputs)
+    dv = default_value if default_value is not None else 0.0
+    if not (0.0 <= dv <= 1.0):
+        raise ValueError("default_value must be between 0.0 and 1.0")
+    ei = float(eval_interval) if eval_interval is not None else None
+    if ei is not None and ei < 0.0:
+        raise ValueError("eval_interval must be >= 0")
+    return TemplateValueSource(
+        **common,
+        template=tpl,
+        inputs=clean_inputs,
+        default_value=dv,
+        eval_interval=ei,
     )
 
 
@@ -381,6 +461,7 @@ CREATE_BUILDERS: Dict[str, CreateBuilder] = {
     "system_metrics": _build_system_metrics,
     "game_event": _build_game_event,
     "http": _build_http,
+    "template": _build_template,
 }
 
 
@@ -569,6 +650,7 @@ def _apply_ha_entity(
     min_ha_value=None,
     max_ha_value=None,
     smoothing=None,
+    normalize=None,
     **_,
 ) -> None:
     if ha_source_id is not None:
@@ -583,6 +665,8 @@ def _apply_ha_entity(
         source.max_ha_value = max_ha_value
     if smoothing is not None:
         source.smoothing = smoothing
+    if normalize is not None:
+        source.normalize = normalize
 
 
 def _apply_gradient_map(
@@ -630,6 +714,7 @@ def _apply_system_metrics(
     sensor_label=None,
     poll_interval=None,
     smoothing=None,
+    normalize=None,
     **_,
 ) -> None:
     if metric is not None:
@@ -650,6 +735,8 @@ def _apply_system_metrics(
         source.poll_interval = poll_interval
     if smoothing is not None:
         source.smoothing = smoothing
+    if normalize is not None:
+        source.normalize = normalize
 
 
 def _apply_game_event(source: GameEventValueSource, **_) -> None:
@@ -667,6 +754,7 @@ def _apply_http(
     min_value=None,
     max_value=None,
     smoothing=None,
+    normalize=None,
     **_,
 ) -> None:
     if http_endpoint_id is not None:
@@ -683,6 +771,47 @@ def _apply_http(
         source.max_value = max_value
     if smoothing is not None:
         source.smoothing = smoothing
+    if normalize is not None:
+        source.normalize = normalize
+
+
+def _apply_template(
+    source: TemplateValueSource,
+    *,
+    template=None,
+    inputs=None,
+    default_value=None,
+    eval_interval=None,
+    **_,
+) -> None:
+    from ledgrab.utils.template_expr import validate_template_expression
+
+    # Compute the prospective final state and validate it BEFORE mutating, so a
+    # rejected update never leaves the cached object half-applied. (inputs/
+    # template may each change independently; unbound vars are checked against
+    # the combined final state.)
+    final_template = template.strip() if template is not None else source.template
+    final_inputs = _validate_template_inputs(inputs) if inputs is not None else source.inputs
+
+    if template is not None:
+        if not final_template:
+            raise ValueError("template expression cannot be empty")
+        validate_template_expression(final_template)
+    if template is not None or inputs is not None:
+        _reject_unbound_template_vars(final_template, final_inputs)
+
+    if template is not None:
+        source.template = final_template
+    if inputs is not None:
+        source.inputs = final_inputs
+    if default_value is not None:
+        if not (0.0 <= default_value <= 1.0):
+            raise ValueError("default_value must be between 0.0 and 1.0")
+        source.default_value = default_value
+    if eval_interval is not None:
+        if eval_interval < 0.0:
+            raise ValueError("eval_interval must be >= 0")
+        source.eval_interval = eval_interval
 
 
 UPDATE_APPLIERS: Dict[str, UpdateApplier] = {
@@ -701,6 +830,7 @@ UPDATE_APPLIERS: Dict[str, UpdateApplier] = {
     "system_metrics": _apply_system_metrics,
     "game_event": _apply_game_event,
     "http": _apply_http,
+    "template": _apply_template,
 }
 
 

server/src/ledgrab/storage/value_source_store.py

@@ -12,7 +12,11 @@ from datetime import datetime, timezone
 
 from ledgrab.storage.base_sqlite_store import BaseSqliteStore
 from ledgrab.storage.database import Database
-from ledgrab.storage.value_source import ValueSource
+from ledgrab.storage.value_source import (
+    GradientMapValueSource,
+    TemplateValueSource,
+    ValueSource,
+)
 from ledgrab.storage.value_source_factories import (
     apply_update as _apply_value_source_update,
     build_source as _build_value_source,
@@ -21,12 +25,18 @@ from ledgrab.utils import get_logger
 
 logger = get_logger(__name__)
 
+# Storage-level cap on value-source reference nesting depth. The runtime acquire
+# backstop (ValueStreamManager) uses a higher cap so legitimate chains never trip
+# it. Color-strip sources cap at 4; value-source chains are flatter combinators.
+MAX_VALUE_SOURCE_DEPTH = 8
+
 
 class ValueSourceStore(BaseSqliteStore[ValueSource]):
     """Persistent storage for value sources."""
 
     _table_name = "value_sources"
     _entity_name = "Value source"
+    _cloneable = True  # no inline secrets — only references shared entities by id
 
     def __init__(self, db: Database):
         super().__init__(db, ValueSource.from_dict)
@@ -66,6 +76,12 @@ class ValueSourceStore(BaseSqliteStore[ValueSource]):
             **kwargs,
         )
 
+        # Reject over-deep reference chains (cycles are impossible at create:
+        # the new id is not yet referenceable by anything).
+        child_ids = self._child_ids_of(source)
+        if child_ids:
+            self.validate_nesting(None, child_ids)
+
         # Name-uniqueness happens last so we never burn a uuid on a source
         # we end up rejecting AND so the user-facing error precedence
         # (type errors before name errors) matches the old code's order.
@@ -87,6 +103,13 @@ class ValueSourceStore(BaseSqliteStore[ValueSource]):
         """
         source = self.get(source_id)
 
+        # Cycle/depth guard FIRST — before any field mutation — so a rejection
+        # never leaves the cached object half-mutated. validate_nesting works
+        # off the prospective child ids derived from kwargs without applying them.
+        child_ids = self._prospective_child_ids(source, kwargs)
+        if child_ids:
+            self.validate_nesting(source_id, child_ids)
+
         name = kwargs.pop("name", None)
         if name is not None:
             self._check_name_unique(name, exclude_id=source_id)
@@ -118,3 +141,110 @@ class ValueSourceStore(BaseSqliteStore[ValueSource]):
 
         logger.info(f"Updated value source: {source_id}")
         return source
+
+    # ── Reference graph (cycle / depth / referential integrity) ──────
+    #
+    # Value sources may reference other value sources: gradient_map via
+    # ``value_source_id`` and template via ``inputs[].value_source_id``. (Note:
+    # css_extract.color_strip_source_id points into the *color strip* store, a
+    # different graph, so it is intentionally not followed here.) Without a
+    # guard, a cycle would infinitely recurse in ValueStreamManager.acquire().
+
+    @staticmethod
+    def _child_ids_of(source: ValueSource) -> list[str]:
+        """Value-source ids that ``source`` references (gradient_map / template)."""
+        if isinstance(source, TemplateValueSource):
+            return [
+                i["value_source_id"]
+                for i in source.inputs
+                if isinstance(i, dict) and i.get("value_source_id")
+            ]
+        if isinstance(source, GradientMapValueSource):
+            return [source.value_source_id] if source.value_source_id else []
+        return []
+
+    def _prospective_child_ids(self, source: ValueSource, kwargs: dict) -> list[str]:
+        """Child ids the source *would* reference after applying ``kwargs``.
+
+        Computed without mutating ``source`` so cycle/depth validation can run
+        before the update is applied (a raise must not leave a half-mutated
+        cached object).
+        """
+        if isinstance(source, TemplateValueSource):
+            inputs = kwargs.get("inputs")
+            if inputs is None:
+                inputs = source.inputs
+            return [
+                i["value_source_id"]
+                for i in (inputs or [])
+                if isinstance(i, dict) and i.get("value_source_id")
+            ]
+        if isinstance(source, GradientMapValueSource):
+            vs_id = kwargs.get("value_source_id")
+            if vs_id is None:
+                vs_id = source.value_source_id
+            return [vs_id] if vs_id else []
+        return []
+
+    def get_transitive_dependencies(self, source_id: str) -> set[str]:
+        """All value-source ids reachable from ``source_id`` via reference edges."""
+        seen: set[str] = set()
+        stack = self._children_of_id(source_id)
+        while stack:
+            cid = stack.pop()
+            if cid in seen:
+                continue
+            seen.add(cid)
+            stack.extend(self._children_of_id(cid))
+        return seen
+
+    def _children_of_id(self, source_id: str) -> list[str]:
+        try:
+            src = self.get(source_id)
+        except Exception:
+            return []
+        return self._child_ids_of(src)
+
+    def _max_depth(self, ids: list[str], visiting: set[str]) -> int:
+        """Longest reference chain length starting at any id in ``ids``."""
+        best = 0
+        for cid in ids:
+            if cid in visiting:
+                continue  # cycle — handled separately; don't recurse forever
+            try:
+                src = self.get(cid)
+            except Exception:
+                depth = 1  # unresolved leaf still counts as one hop
+            else:
+                depth = 1 + self._max_depth(self._child_ids_of(src), visiting | {cid})
+            best = max(best, depth)
+        return best
+
+    def validate_nesting(self, parent_id: str | None, child_ids: list[str]) -> None:
+        """Reject self-reference, circular dependencies, and over-deep nesting.
+
+        ``parent_id`` is ``None`` at create time — a brand-new node has no id, so
+        no existing source can reference it and a cycle through it is impossible;
+        only the depth check applies. At update time the cycle check runs too.
+        """
+        if 1 + self._max_depth(child_ids, set()) > MAX_VALUE_SOURCE_DEPTH:
+            raise ValueError(
+                f"value source reference chain too deep (max {MAX_VALUE_SOURCE_DEPTH})"
+            )
+        if parent_id is None:
+            return
+        for cid in child_ids:
+            if cid == parent_id:
+                raise ValueError("a value source cannot reference itself")
+            if parent_id in self.get_transitive_dependencies(cid):
+                raise ValueError(f"input {cid!r} creates a circular value-source dependency")
+
+    def find_referencing_sources(self, source_id: str) -> list[str]:
+        """Names of value sources that reference ``source_id`` (for delete-protection)."""
+        names: list[str] = []
+        for src in self.get_all():
+            if src.id == source_id:
+                continue
+            if source_id in self._child_ids_of(src):
+                names.append(src.name)
+        return names

server/src/ledgrab/storage/wled_output_target.py

@@ -24,6 +24,11 @@ class WledOutputTarget(OutputTarget, type_key="led"):
     min_brightness_threshold: BindableFloat = field(default_factory=lambda: BindableFloat(0.0))
     adaptive_fps: bool = False  # auto-reduce FPS when device is unresponsive
     protocol: str = "ddp"  # "ddp" (UDP) or "http" (JSON API)
+    # Automatic brightness limiting (ABL): cap estimated strip draw to a PSU
+    # budget. max_milliamps <= 0 disables it. milliamps_per_led is the full-white
+    # draw of one LED (WS2812-class default 55 mA).
+    max_milliamps: int = 0
+    milliamps_per_led: int = 55
 
     def register_with_manager(self, manager) -> None:
         """Register this WLED target with the processor manager."""
@@ -39,6 +44,8 @@ class WledOutputTarget(OutputTarget, type_key="led"):
                 min_brightness_threshold=self.min_brightness_threshold,
                 adaptive_fps=self.adaptive_fps,
                 protocol=self.protocol,
+                max_milliamps=self.max_milliamps,
+                milliamps_per_led=self.milliamps_per_led,
             )
 
     def sync_with_manager(
@@ -59,6 +66,8 @@ class WledOutputTarget(OutputTarget, type_key="led"):
                     "state_check_interval": self.state_check_interval,
                     "min_brightness_threshold": self.min_brightness_threshold,
                     "adaptive_fps": self.adaptive_fps,
+                    "max_milliamps": self.max_milliamps,
+                    "milliamps_per_led": self.milliamps_per_led,
                 },
             )
         if css_changed:
@@ -81,6 +90,8 @@ class WledOutputTarget(OutputTarget, type_key="led"):
         min_brightness_threshold=None,
         adaptive_fps=None,
         protocol=None,
+        max_milliamps=None,
+        milliamps_per_led=None,
         description=None,
         tags: List[str] | None = None,
         icon: str | None = None,
@@ -122,6 +133,10 @@ class WledOutputTarget(OutputTarget, type_key="led"):
             self.adaptive_fps = adaptive_fps
         if protocol is not None:
             self.protocol = protocol
+        if max_milliamps is not None:
+            self.max_milliamps = max(0, int(max_milliamps))
+        if milliamps_per_led is not None:
+            self.milliamps_per_led = max(1, int(milliamps_per_led))
 
     @property
     def has_picture_source(self) -> bool:
@@ -139,6 +154,8 @@ class WledOutputTarget(OutputTarget, type_key="led"):
         d["min_brightness_threshold"] = self.min_brightness_threshold.to_dict()
         d["adaptive_fps"] = self.adaptive_fps
         d["protocol"] = self.protocol
+        d["max_milliamps"] = self.max_milliamps
+        d["milliamps_per_led"] = self.milliamps_per_led
         return d
 
     @classmethod
@@ -165,6 +182,8 @@ class WledOutputTarget(OutputTarget, type_key="led"):
             ),
             adaptive_fps=data.get("adaptive_fps", False),
             protocol=data.get("protocol", "ddp"),
+            max_milliamps=int(data.get("max_milliamps", 0) or 0),
+            milliamps_per_led=int(data.get("milliamps_per_led", 55) or 55),
             description=data.get("description"),
             tags=data.get("tags", []),
             icon=data.get("icon", ""),

server/src/ledgrab/templates/modals/target-editor.html

@@ -138,6 +138,22 @@
                                     <small class="input-hint" style="display:none" data-i18n="targets.keepalive_interval.hint">How often to resend the last frame when the screen is static, to keep the device in live mode (0.5-5.0s)</small>
                                     <input type="range" id="target-editor-keepalive-interval" min="0.5" max="5.0" step="0.5" value="1.0" oninput="document.getElementById('target-editor-keepalive-interval-value').textContent = this.value">
                                 </div>
+
+                                <div class="form-group" id="target-editor-power-limit-group">
+                                    <div class="label-row">
+                                        <label for="target-editor-max-milliamps" data-i18n="targets.power_limit">Max current (ABL):</label>
+                                        <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?">?</button>
+                                    </div>
+                                    <small class="input-hint" style="display:none" data-i18n="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.</small>
+                                    <div class="label-row">
+                                        <input type="number" id="target-editor-max-milliamps" min="0" max="200000" step="100" value="0">
+                                        <span data-i18n="targets.power_limit.ma_suffix">mA (0 = unlimited)</span>
+                                    </div>
+                                    <div class="label-row">
+                                        <label for="target-editor-ma-per-led" data-i18n="targets.power_limit.per_led">mA per LED (full white):</label>
+                                        <input type="number" id="target-editor-ma-per-led" min="1" max="200" step="1" value="55">
+                                    </div>
+                                </div>
                             </div>
                         </details>
                     </div>

server/src/ledgrab/templates/modals/value-source-editor.html

@@ -62,6 +62,7 @@
                         <option value="css_extract" data-i18n="value_source.type.css_extract">Strip Extract</option>
                         <option value="system_metrics" data-i18n="value_source.type.system_metrics">System Metrics</option>
                         <option value="http" data-i18n="value_source.type.http">HTTP Poll</option>
+                        <option value="template" data-i18n="value_source.type.template">Jinja Template</option>
                     </select>
                 </div>
 
@@ -394,6 +395,18 @@
                         <input type="text" id="value-source-attribute" placeholder="">
                     </div>
 
+                    <div class="form-group">
+                        <div class="label-row">
+                            <label for="value-source-ha-normalize" data-i18n="value_source.normalize">Normalize to 0–1:</label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="value_source.normalize.hint">On: rescale the raw value to 0–1 using Min/Max below. Off: the value is clamped to 0–1 as-is (for entities that already report a 0–1 fraction). The raw value is always available to templates (raw[name]) and automations.</small>
+                        <label class="settings-toggle">
+                            <input type="checkbox" id="value-source-ha-normalize" checked onchange="onValueSourceNormalizeChange()">
+                            <span class="settings-toggle-slider"></span>
+                        </label>
+                    </div>
+
                     <div class="form-group">
                         <div class="label-row">
                             <label for="value-source-min-ha-value"><span data-i18n="value_source.min_ha_value">Min HA Value:</span> <span id="value-source-min-ha-value-display">0</span></label>
@@ -456,6 +469,82 @@
                     </div>
                 </div>
 
+                <!-- Template (Jinja expression) fields -->
+                <div id="value-source-template-section" style="display:none">
+                    <div class="form-group">
+                        <div class="label-row">
+                            <label for="value-source-template-expression" data-i18n="value_source.template.expression">Expression:</label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="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.</small>
+                        <!-- The highlight overlay is injected around this textarea by jinja-editor.ts -->
+                        <textarea id="value-source-template-expression" rows="3" spellcheck="false"
+                            data-i18n-placeholder="value_source.template.expression.placeholder"
+                            placeholder="clamp((temp - 18) / 10, 0, 1)"></textarea>
+                        <div id="value-source-template-error" class="field-error-msg" style="display:none"></div>
+                        <div id="value-source-template-ok" class="field-ok-msg" style="display:none"></div>
+                        <div id="value-source-template-warn" class="field-warn-msg" style="display:none"></div>
+
+                        <details class="jinja-hints">
+                            <summary data-i18n="value_source.template.hints.title">Expression help</summary>
+                            <div class="jinja-hints-body">
+                                <div class="jinja-hints-section">
+                                    <span class="jinja-hints-section-title" data-i18n="value_source.template.hints.inputs_title">Bound inputs</span>
+                                    <div id="value-source-template-hint-vars" class="jinja-hints-vars"></div>
+                                </div>
+                                <div class="jinja-hints-section">
+                                    <span class="jinja-hints-section-title" data-i18n="value_source.template.hints.globals_title">Globals</span>
+                                    <div data-i18n="value_source.template.hints.globals">min(a, b), max(a, b), abs(x), round(x), clamp(x, lo, hi)</div>
+                                </div>
+                                <div class="jinja-hints-section">
+                                    <span class="jinja-hints-section-title" data-i18n="value_source.template.hints.raw_title">Raw values</span>
+                                    <div data-i18n="value_source.template.hints.raw">raw[name] gives the un-normalized value of an input that has one.</div>
+                                </div>
+                                <div class="jinja-hints-section">
+                                    <span class="jinja-hints-section-title" data-i18n="value_source.template.hints.examples_title">Examples</span>
+                                    <ul class="jinja-hints-examples">
+                                        <li><code>min(audio * 2, 1)</code></li>
+                                        <li><code>clamp((temp - 18) / 10, 0, 1)</code></li>
+                                        <li><code>(a + b) / 2</code></li>
+                                    </ul>
+                                </div>
+                                <div class="jinja-hints-section">
+                                    <small class="jinja-hints-time" data-i18n="value_source.template.hints.time">Tip: for time-of-day logic, bind an Adaptive (Time) or Daylight source as an input.</small>
+                                </div>
+                            </div>
+                        </details>
+                    </div>
+
+                    <div class="form-group">
+                        <div class="label-row">
+                            <label data-i18n="value_source.template.inputs">Inputs:</label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="value_source.template.inputs.hint">Bind float value sources to variable names you reference in the expression.</small>
+                        <div id="value-source-template-inputs-list" class="template-inputs-list"></div>
+                        <button type="button" class="btn btn-secondary btn-sm" onclick="addTemplateInput()" data-i18n="value_source.template.add_input">+ Add Input</button>
+                    </div>
+
+                    <div class="form-group">
+                        <div class="label-row">
+                            <label for="value-source-template-default-value"><span data-i18n="value_source.template.default_value">Default Value:</span> <span id="value-source-template-default-value-display">0.00</span></label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="value_source.template.default_value.hint">Output used when the expression cannot be evaluated (e.g. an input is missing).</small>
+                        <input type="range" id="value-source-template-default-value" min="0" max="1" step="0.01" value="0"
+                            oninput="document.getElementById('value-source-template-default-value-display').textContent = parseFloat(this.value).toFixed(2)">
+                    </div>
+
+                    <div class="form-group">
+                        <div class="label-row">
+                            <label for="value-source-template-eval-interval" data-i18n="value_source.template.eval_interval">Eval Interval (s):</label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="value_source.template.eval_interval.hint">How often to re-evaluate the expression. 0 = every poll (re-evaluate as fast as the inputs update).</small>
+                        <input type="number" id="value-source-template-eval-interval" min="0" step="0.1" value="0">
+                    </div>
+                </div>
+
                 <!-- CSS Extract fields -->
                 <div id="value-source-css-extract-section" style="display:none">
                     <div class="form-group">
@@ -509,6 +598,18 @@
                         </select>
                     </div>
 
+                    <div class="form-group" id="value-source-sysmetric-normalize-group">
+                        <div class="label-row">
+                            <label for="value-source-sysmetric-normalize" data-i18n="value_source.normalize">Normalize to 0–1:</label>
+                            <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                        </div>
+                        <small class="input-hint" style="display:none" data-i18n="value_source.normalize.hint">On: rescale the raw value to 0–1 using Min/Max below. Off: the value is clamped to 0–1 as-is (for metrics that already report a 0–1 fraction). The raw value is always available to templates (raw[name]) and automations.</small>
+                        <label class="settings-toggle">
+                            <input type="checkbox" id="value-source-sysmetric-normalize" checked onchange="onValueSourceNormalizeChange()">
+                            <span class="settings-toggle-slider"></span>
+                        </label>
+                    </div>
+
                     <div id="value-source-sysmetric-range" style="display:none">
                         <div class="form-group">
                             <label for="value-source-sysmetric-min"><span data-i18n="value_source.sysmetric.min">Min Value:</span></label>
@@ -670,6 +771,17 @@
                         <summary data-i18n="value_source.http.modulator.summary">Modulator mapping (optional)</summary>
                         <div class="form-collapse-body">
                             <small class="input-hint" data-i18n="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.</small>
+                            <div class="form-group">
+                                <div class="label-row">
+                                    <label for="value-source-http-normalize" data-i18n="value_source.normalize">Normalize to 0–1:</label>
+                                    <button type="button" class="hint-toggle" onclick="toggleHint(this)" title="?" data-i18n-aria-label="aria.hint">?</button>
+                                </div>
+                                <small class="input-hint" style="display:none" data-i18n="value_source.normalize.hint">On: rescale the raw value to 0–1 using Min/Max below. Off: the value is clamped to 0–1 as-is (for endpoints that already return a 0–1 fraction). The raw value is always available to templates (raw[name]) and automations.</small>
+                                <label class="settings-toggle">
+                                    <input type="checkbox" id="value-source-http-normalize" checked onchange="onValueSourceNormalizeChange()">
+                                    <span class="settings-toggle-slider"></span>
+                                </label>
+                            </div>
                             <div class="form-group">
                                 <div class="label-row">
                                     <label for="value-source-http-min" data-i18n="value_source.http.min_value">Min Value:</label>

server/src/ledgrab/utils/__init__.py

@@ -3,6 +3,7 @@
 from .file_ops import atomic_write_json, read_upload_capped
 from .logger import setup_logging, get_logger
 from .monitor_names import get_monitor_names, get_monitor_name, get_monitor_refresh_rates
+from .numeric import clamp01
 from .timer import high_resolution_timer
 from .log_broadcaster import broadcaster as log_broadcaster, install_broadcast_handler
 from .url_scheme import infer_http_scheme
@@ -15,6 +16,7 @@ __all__ = [
     "get_monitor_names",
     "get_monitor_name",
     "get_monitor_refresh_rates",
+    "clamp01",
     "high_resolution_timer",
     "log_broadcaster",
     "install_broadcast_handler",

server/src/ledgrab/utils/numeric.py

@@ -0,0 +1,24 @@
+"""Small numeric helpers shared across the processing layer."""
+
+from __future__ import annotations
+
+import math
+
+
+def clamp01(x: float, default: float = 0.0) -> float:
+    """Clamp ``x`` into the unit interval ``[0.0, 1.0]``, finite-safe.
+
+    NaN/inf are rejected to ``default`` *before* clamping — they are valid
+    floats, so ``max/min`` alone would silently pass them through (and an
+    ``int(base * inf)`` cast downstream raises OverflowError, ``int(nan)``
+    raises ValueError). Use this at any boundary that feeds a value into a
+    fixed-point / uint brightness multiply where a non-finite or out-of-range
+    value would corrupt or crash the math.
+    """
+    if not math.isfinite(x):
+        return default
+    if x < 0.0:
+        return 0.0
+    if x > 1.0:
+        return 1.0
+    return x

server/src/ledgrab/utils/template_expr.py

@@ -0,0 +1,209 @@
+"""Hardened sandboxed-Jinja expression engine for template value sources.
+
+Single source of truth for compiling, validating, and evaluating user-authored
+Jinja *expressions* that combine the live values of other value sources into a
+single float in [0, 1]. Imported by the storage factory (create/update
+validation), the runtime ``TemplateValueStream``, and the validate-template API
+route, so the client and server can never disagree about what is valid.
+
+Security model — a user-authored expression is attacker-influenceable config
+that runs server-side (LAN device, shareable backups), so we layer defenses:
+
+* :class:`~jinja2.sandbox.ImmutableSandboxedEnvironment` blocks ``__class__`` /
+  ``mro`` traversal, mutation, and unsafe attribute/method access.
+* ALL default filters and tests are stripped (``|attr``, ``|pprint``, ``|map``,
+  ``|format`` …) and the auto-injected globals (``range``, ``dict``,
+  ``namespace``, ``cycler``, ``lipsum``, ``joiner``) are removed — none are
+  needed for numeric math and several are escape/DoS amplifiers.
+* Only five vetted numeric callables are exposed: ``min``, ``max``, ``abs``,
+  ``round``, ``clamp``.
+* The evaluation context contains ONLY primitive floats plus a flat dict of
+  floats (``raw``) — never any application object — so even a hypothetical
+  sandbox escape has nothing privileged to pivot to.
+* Obvious cost bombs are rejected at validate time: the ``**`` (power) operator
+  and string/list ``*`` repetition can hang or OOM the interpreter, which
+  ``try/except`` cannot catch.
+* The result is coerced to float, NaN/inf are rejected (they are valid floats,
+  not exceptions, so clamping alone would silently keep them), then clamped.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any
+
+from jinja2 import nodes
+from jinja2.exceptions import TemplateError
+from jinja2.sandbox import ImmutableSandboxedEnvironment
+
+
+def clamp(x: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    """Clamp ``x`` into ``[lo, hi]`` (defaults to the unit interval)."""
+    return max(lo, min(hi, x))
+
+
+# The five callables a template author may use. Kept as the *only* names in the
+# environment globals so no other builtin/Jinja helper is reachable.
+GLOBALS: dict[str, Any] = {
+    "min": min,
+    "max": max,
+    "abs": abs,
+    "round": round,
+    "clamp": clamp,
+}
+
+# Input variable names that would shadow a global or the ``raw`` dict (and thus
+# silently break the expression) or that Jinja auto-injects. Rejected at save
+# time so the user gets a clear error instead of a template that always falls
+# back to ``default_value``.
+RESERVED_NAMES: frozenset[str] = frozenset(
+    {*GLOBALS, "raw", "range", "dict", "namespace", "cycler", "lipsum", "joiner"}
+)
+
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class TemplateValidationError(ValueError):
+    """Raised when a template expression (or an input name) is invalid/unsafe.
+
+    Subclasses :class:`ValueError` so existing route handlers that map
+    ``ValueError -> HTTP 400`` surface a clean message automatically.
+    """
+
+
+def _build_env() -> ImmutableSandboxedEnvironment:
+    env = ImmutableSandboxedEnvironment(autoescape=False)
+    # Strip the entire default filter/test surface — numeric expressions need
+    # none of them, and |attr/|pprint/|map/|format are escape/DoS amplifiers.
+    env.filters.clear()
+    env.tests.clear()
+    # Replace the auto-injected globals (range/dict/namespace/cycler/...) with
+    # only our five vetted callables.
+    env.globals.clear()
+    env.globals.update(GLOBALS)
+    return env
+
+
+# Module-level shared environment. Compiled expressions and evaluation are
+# cheap; the environment itself is immutable config built once.
+SANDBOX_ENV = _build_env()
+
+
+def _clean_jinja_error(exc: TemplateError) -> str:
+    """A user-facing one-line message from a Jinja compile error."""
+    msg = str(exc) or exc.__class__.__name__
+    return msg.strip()
+
+
+def _guard_ast(template: str) -> None:
+    """Reject cost-bomb / disallowed constructs via the Jinja AST.
+
+    Called only on already-compilable single expressions, so wrapping in an
+    output block is safe (a ``}}`` inside a string literal stays inside it).
+    """
+    try:
+        tree = SANDBOX_ENV.parse("{{ (" + template + ") }}")
+    except TemplateError as exc:  # pragma: no cover - compile already gated this
+        raise TemplateValidationError(_clean_jinja_error(exc)) from exc
+
+    if next(tree.find_all(nodes.Pow), None) is not None:
+        raise TemplateValidationError("the '**' (power) operator is not allowed")
+
+    if next(tree.find_all((nodes.Filter, nodes.Test)), None) is not None:
+        raise TemplateValidationError("filters and tests are not allowed")
+
+    # Collection literals have no use in a numeric expression and enable a
+    # memory-bomb via repetition ([0] * 10**8 allocates gigabytes). The only
+    # collection access we need is raw[...] subscript, which is a Getitem, not a
+    # literal. Forbid list/tuple/dict literals outright.
+    if next(tree.find_all((nodes.List, nodes.Tuple, nodes.Dict)), None) is not None:
+        raise TemplateValidationError("list/tuple/dict literals are not allowed")
+
+    # Attribute access (``a.b``) has no use in numeric expressions and is the
+    # classic sandbox-escape vector (``__class__``, ``.format`` …). Raw values
+    # are read by subscript (``raw['x']``), which stays allowed.
+    if next(tree.find_all(nodes.Getattr), None) is not None:
+        raise TemplateValidationError("attribute access ('.') is not allowed")
+
+    # Only the five vetted globals may be called — blocks dict()/namespace()/
+    # cycler()/etc. at validate time with a clear message (they would also fail
+    # at runtime since the environment globals are cleared, but failing early is
+    # better UX and defense in depth).
+    for call in tree.find_all(nodes.Call):
+        fn = call.node
+        if not (isinstance(fn, nodes.Name) and fn.name in GLOBALS):
+            name = getattr(fn, "name", None) or fn.__class__.__name__
+            raise TemplateValidationError(
+                f"only min/max/abs/round/clamp may be called (got {name!r})"
+            )
+
+    # float * float is fine; reject only string/list repetition (the OOM path).
+    for mul in tree.find_all(nodes.Mul):
+        for side in (mul.left, mul.right):
+            if isinstance(side, nodes.Const) and isinstance(side.value, (str, list, tuple)):
+                raise TemplateValidationError("string/list repetition is not allowed")
+
+
+def compile_template(template: str):
+    """Compile ``template`` to a reusable Jinja ``Expression``.
+
+    Raises :class:`TemplateValidationError` if empty, uncompilable, or it uses a
+    disallowed/cost-bomb construct. Globals (min/max/abs/round/clamp) resolve
+    from ``SANDBOX_ENV.globals`` at call time, so the returned expression is
+    invoked with only the data context: ``expr(**ctx)``.
+    """
+    if not template or not template.strip():
+        raise TemplateValidationError("expression is empty")
+    try:
+        expr = SANDBOX_ENV.compile_expression(template)
+    except TemplateError as exc:
+        raise TemplateValidationError(_clean_jinja_error(exc)) from exc
+    _guard_ast(template)
+    return expr
+
+
+def validate_template_expression(template: str) -> None:
+    """Validate ``template`` (compile + guard); raise on any problem."""
+    compile_template(template)
+
+
+def validate_input_name(name: str) -> None:
+    """Validate a single template input variable name; raise on any problem."""
+    if not name or not _IDENT_RE.match(name):
+        raise TemplateValidationError(f"input name {name!r} is not a valid identifier")
+    if name in RESERVED_NAMES:
+        raise TemplateValidationError(f"input name {name!r} is reserved")
+
+
+def extract_variables(template: str) -> list[str]:
+    """Return the free input variables referenced by ``template``.
+
+    Excludes the globals and ``raw`` so the validate endpoint reports only the
+    names the author is expected to bind. Returns ``[]`` if unparsable.
+    """
+    from jinja2 import meta
+
+    try:
+        tree = SANDBOX_ENV.parse("{{ (" + template + ") }}")
+    except TemplateError:
+        return []
+    undeclared = meta.find_undeclared_variables(tree)
+    return sorted(undeclared - set(GLOBALS) - {"raw"})
+
+
+def finalize_result(value: Any, default: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    """Coerce an evaluated result to a safe float in ``[lo, hi]``.
+
+    Non-numeric → ``default``; NaN/inf → ``default`` (they are valid floats, so
+    clamping alone would silently keep them); otherwise clamp.
+    """
+    try:
+        f = float(value)
+    except (TypeError, ValueError, OverflowError):
+        # OverflowError: float() of a multi-hundred-digit int (e.g. a chained
+        # big-int multiply). Treated as "not a usable number" → default.
+        return default
+    if math.isnan(f) or math.isinf(f):
+        return default
+    return clamp(f, lo, hi)

server/tests/api/routes/test_system_routes.py

@@ -92,3 +92,57 @@ class TestRootEndpoint:
         resp = client.get("/")
         assert resp.status_code == 200
         assert "text/html" in resp.headers["content-type"]
+
+
+class TestInstalledAppsEndpoint:
+    def test_requires_auth(self, client):
+        resp = client.get("/api/v1/system/installed-apps")
+        assert resp.status_code == 401
+
+    def test_empty_off_android(self, client):
+        """Desktop test host: is_android() is False, so the bridge wrapper
+        short-circuits to an empty list."""
+        resp = client.get("/api/v1/system/installed-apps", headers=_auth_headers())
+        assert resp.status_code == 200
+        assert resp.json() == {"apps": [], "count": 0}
+
+    def test_returns_apps_when_available(self, client, monkeypatch):
+        from ledgrab.core.automations import platform_detector as pd
+
+        monkeypatch.setattr(
+            pd,
+            "list_installed_apps",
+            lambda: [{"package": "com.netflix.mediaclient", "label": "Netflix"}],
+        )
+        resp = client.get("/api/v1/system/installed-apps", headers=_auth_headers())
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["count"] == 1
+        assert data["apps"][0] == {"package": "com.netflix.mediaclient", "label": "Netflix"}
+
+
+class TestSystemInfoEndpoint:
+    def test_requires_auth(self, client):
+        resp = client.get("/api/v1/system/info")
+        assert resp.status_code == 401
+
+    def test_desktop_signal(self, client):
+        resp = client.get("/api/v1/system/info", headers=_auth_headers())
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["is_android"] is False
+        assert data["app_match_kind"] == "process"
+        assert data["usage_access_granted"] is True
+
+    def test_android_signal(self, client, monkeypatch):
+        import ledgrab.utils.platform as plat
+        from ledgrab.core.automations import platform_detector as pd
+
+        monkeypatch.setattr(plat, "is_android", lambda: True)
+        monkeypatch.setattr(pd, "has_usage_access", lambda: False)
+        resp = client.get("/api/v1/system/info", headers=_auth_headers())
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["is_android"] is True
+        assert data["app_match_kind"] == "package"
+        assert data["usage_access_granted"] is False

server/tests/api/routes/test_template_value_source_routes.py

@@ -0,0 +1,182 @@
+"""Tests for template value source API: CRUD, validate-template, delete-protection."""
+
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from ledgrab.api import dependencies as deps
+from ledgrab.api.routes.value_sources import router
+from ledgrab.storage.value_source_store import ValueSourceStore
+
+
+@pytest.fixture
+def _route_db(tmp_path):
+    from ledgrab.storage.database import Database
+
+    db = Database(tmp_path / "test.db")
+    yield db
+    db.close()
+
+
+@pytest.fixture
+def store(_route_db):
+    return ValueSourceStore(_route_db)
+
+
+@pytest.fixture
+def client(store):
+    app = FastAPI()
+    app.include_router(router)
+
+    from ledgrab.api.auth import verify_api_key
+
+    app.dependency_overrides[verify_api_key] = lambda: "test-user"
+    app.dependency_overrides[deps.get_value_source_store] = lambda: store
+    app.dependency_overrides[deps.get_processor_manager] = lambda: MagicMock()
+    app.dependency_overrides[deps.get_output_target_store] = lambda: MagicMock(
+        get_all_targets=lambda: []
+    )
+
+    deps._deps["processor_manager"] = MagicMock()
+    return TestClient(app, raise_server_exceptions=False)
+
+
+def _create(client, **over):
+    body = {
+        "source_type": "template",
+        "name": "Combo",
+        "template": "min(a * 2, 1)",
+        "inputs": [{"name": "a", "value_source_id": ""}],
+        "default_value": 0.2,
+    }
+    body.update(over)
+    return client.post("/api/v1/value-sources", json=body)
+
+
+class TestCRUD:
+    def test_create_get_list_roundtrip(self, client):
+        r = _create(client)
+        assert r.status_code == 201, r.text
+        body = r.json()
+        assert body["source_type"] == "template"
+        assert body["return_type"] == "float"
+        assert body["template"] == "min(a * 2, 1)"
+        assert body["inputs"] == [{"name": "a", "value_source_id": ""}]
+        assert body["default_value"] == 0.2
+        sid = body["id"]
+
+        got = client.get(f"/api/v1/value-sources/{sid}").json()
+        assert got["template"] == "min(a * 2, 1)"
+
+        lst = client.get("/api/v1/value-sources").json()
+        assert any(s["id"] == sid and s["source_type"] == "template" for s in lst["sources"])
+
+    def test_update(self, client):
+        sid = _create(client).json()["id"]
+        r = client.put(
+            f"/api/v1/value-sources/{sid}",
+            json={"source_type": "template", "template": "clamp(a * 3)"},
+        )
+        assert r.status_code == 200, r.text
+        assert r.json()["template"] == "clamp(a * 3)"
+
+    def test_create_compile_error_returns_400(self, client):
+        r = _create(client, template="a +")
+        assert r.status_code == 400
+
+    def test_create_reserved_name_returns_400(self, client):
+        r = _create(client, inputs=[{"name": "min", "value_source_id": ""}])
+        assert r.status_code == 400
+
+
+class TestDeleteProtection:
+    def test_delete_blocked_when_referenced(self, client):
+        base = client.post(
+            "/api/v1/value-sources",
+            json={"source_type": "static", "name": "Base", "value": 0.5},
+        ).json()
+        _create(
+            client,
+            name="Uses",
+            template="b",
+            inputs=[{"name": "b", "value_source_id": base["id"]}],
+        )
+        r = client.delete(f"/api/v1/value-sources/{base['id']}")
+        assert r.status_code == 400
+        assert "referenced by" in r.json()["detail"]
+
+
+class TestValidateEndpoint:
+    def _validate(self, client, **body):
+        return client.post("/api/v1/value-sources/validate-template", json=body)
+
+    def test_valid_expression(self, client):
+        r = self._validate(
+            client,
+            template="min(a, b)",
+            inputs=[{"name": "a", "value_source_id": ""}, {"name": "b", "value_source_id": ""}],
+        )
+        assert r.status_code == 200
+        data = r.json()
+        assert data["valid"] is True
+        assert set(data["variables"]) == {"a", "b"}
+
+    def test_compile_error(self, client):
+        r = self._validate(client, template="a +", inputs=[])
+        data = r.json()
+        assert data["valid"] is False
+        assert data["error"]
+
+    def test_reserved_name(self, client):
+        r = self._validate(
+            client, template="min(0,1)", inputs=[{"name": "raw", "value_source_id": ""}]
+        )
+        assert r.json()["valid"] is False
+
+    def test_missing_input_is_warning_not_error(self, client):
+        r = self._validate(
+            client, template="a", inputs=[{"name": "a", "value_source_id": "vs_nope"}]
+        )
+        data = r.json()
+        assert data["valid"] is True
+        assert data["warnings"]
+
+    def test_unbound_variable_is_error(self, client):
+        # Typo: expression uses 'ha_enti' but the input is named 'ha_entity'.
+        r = self._validate(
+            client, template="ha_enti", inputs=[{"name": "ha_entity", "value_source_id": ""}]
+        )
+        data = r.json()
+        assert data["valid"] is False
+        assert any("unbound" in e for e in data["errors"])
+
+    def test_cycle_detected_with_id(self, client):
+        t1 = _create(client, name="T1", template="clamp(0.5)", inputs=[]).json()
+        t2 = _create(
+            client,
+            name="T2",
+            template="x",
+            inputs=[{"name": "x", "value_source_id": t1["id"]}],
+        ).json()
+        # Editing t1 to point at t2 would close a cycle.
+        r = self._validate(
+            client, template="x", inputs=[{"name": "x", "value_source_id": t2["id"]}], id=t1["id"]
+        )
+        assert r.json()["valid"] is False
+
+
+class TestResponseMapCoverage:
+    def test_template_in_response_map(self):
+        from ledgrab.api.routes.value_sources import _RESPONSE_MAP
+        from ledgrab.storage.value_source import TemplateValueSource
+
+        assert TemplateValueSource in _RESPONSE_MAP
+
+    def test_template_in_all_unions(self):
+        from ledgrab.api.schemas import value_sources as sch
+
+        for union_name in ("ValueSourceResponse", "ValueSourceCreate", "ValueSourceUpdate"):
+            src = repr(getattr(sch, union_name))
+            assert "template" in src.lower() or "Template" in src

server/tests/api/test_graph_duplicate.py

@@ -0,0 +1,171 @@
+"""Integration tests for server-side subgraph duplication.
+
+Exercises ``_duplicate_subgraph`` against the *real* value-source and
+colour-strip stores (temp DB), asserting that references *within* the selection
+are remapped to the clones while references to entities *outside* the selection
+stay shared with the originals — and that the deep-copy clone preserves config.
+"""
+
+import pytest
+
+from ledgrab.api import dependencies as deps
+from ledgrab.api.graph_schema import serialize_entity
+from ledgrab.api.routes.graph import _duplicate_subgraph
+from ledgrab.storage.color_strip_store import ColorStripStore
+from ledgrab.storage.database import Database
+from ledgrab.storage.value_source_store import ValueSourceStore
+
+
+@pytest.fixture
+def stores(tmp_path, monkeypatch):
+    db = Database(tmp_path / "dup.db")
+    css = ColorStripStore(db)
+    vss = ValueSourceStore(db)
+    monkeypatch.setattr(deps, "_deps", {"color_strip_store": css, "value_source_store": vss})
+    yield css, vss
+    db.close()
+
+
+def _layer(sid: str) -> dict:
+    return {"source_id": sid, "blend_mode": "normal", "opacity": 1.0, "enabled": True}
+
+
+def test_duplicate_composite_remaps_only_in_selection_refs(stores):
+    css, _vss = stores
+    b = css.create_source(name="B", source_type="single_color", colors=[[255, 0, 0]])
+    d = css.create_source(name="D", source_type="single_color", colors=[[0, 255, 0]])
+    a = css.create_source(name="A", source_type="composite", layers=[_layer(b.id), _layer(d.id)])
+
+    res = _duplicate_subgraph([a.id, b.id], " (copy)")
+
+    assert set(res["id_map"]) == {a.id, b.id}
+    assert res["skipped"] == []
+    assert res["warnings"] == []
+
+    a_new = serialize_entity(css.get(res["id_map"][a.id]))
+    layer_ids = [ly["source_id"] for ly in a_new["layers"]]
+    # B was in the selection -> remapped to the clone; D was not -> stays shared.
+    assert layer_ids == [res["id_map"][b.id], d.id]
+    assert a_new["name"] == "A (copy)"
+    # Original is untouched.
+    assert [ly["source_id"] for ly in serialize_entity(css.get(a.id))["layers"]] == [b.id, d.id]
+
+
+def test_duplicate_preserves_clone_config(stores):
+    """The deep-copy clone keeps every field except identity/name/timestamps —
+    guarding against the storage-vs-create-schema name mismatch (e.g. single
+    color's ``colors``) that a create-schema round-trip would silently drop."""
+    css, _vss = stores
+    src = css.create_source(name="Solid", source_type="single_color", colors=[[12, 34, 56]])
+    res = _duplicate_subgraph([src.id], " (copy)")
+    orig = serialize_entity(css.get(src.id))
+    clone = serialize_entity(css.get(res["id_map"][src.id]))
+    ignore = {"id", "name", "created_at", "updated_at"}
+    assert {k: v for k, v in clone.items() if k not in ignore} == {
+        k: v for k, v in orig.items() if k not in ignore
+    }
+
+
+def test_duplicate_partial_selection_keeps_layer_refs_shared(stores):
+    css, _vss = stores
+    b = css.create_source(name="B", source_type="single_color", colors=[[255, 0, 0]])
+    a = css.create_source(name="A", source_type="composite", layers=[_layer(b.id)])
+
+    res = _duplicate_subgraph([a.id], " (copy)")  # only the composite, not its layer
+
+    a_new = serialize_entity(css.get(res["id_map"][a.id]))
+    assert [ly["source_id"] for ly in a_new["layers"]] == [b.id]  # shared with original
+
+
+def test_duplicate_remaps_bindable_slot_to_cloned_value_source(stores):
+    """Pass-2's dict round-trip path: a colour-strip bindable slot bound to a
+    value source that is *also* in the selection must point at the value clone
+    (not the original) after duplication."""
+    css, vss = stores
+    vs = vss.create_source(name="Pulse", source_type="static", value=0.5)
+    c = css.create_source(name="Candle", source_type="candlelight")
+    css.update_source(c.id, intensity={"source_id": vs.id})  # bind intensity -> vs
+    assert serialize_entity(css.get(c.id))["intensity"]["source_id"] == vs.id  # binding took
+
+    res = _duplicate_subgraph([c.id, vs.id], " (copy)")
+
+    assert res["warnings"] == []
+    c_new = serialize_entity(css.get(res["id_map"][c.id]))
+    assert c_new["intensity"]["source_id"] == res["id_map"][vs.id]
+
+
+def test_duplicate_remaps_layer_brightness_source(stores):
+    """A composite layer's value-source brightness binding (list + value ref) is
+    remapped when that value source is also in the selection."""
+    css, vss = stores
+    vs = vss.create_source(name="Dim", source_type="static", value=0.3)
+    leaf = css.create_source(name="Leaf", source_type="single_color", colors=[[9, 9, 9]])
+    comp = css.create_source(
+        name="Comp",
+        source_type="composite",
+        layers=[{**_layer(leaf.id), "brightness_source_id": vs.id}],
+    )
+    res = _duplicate_subgraph([comp.id, leaf.id, vs.id], " (copy)")
+    layer = serialize_entity(css.get(res["id_map"][comp.id]))["layers"][0]
+    assert layer["source_id"] == res["id_map"][leaf.id]
+    assert layer["brightness_source_id"] == res["id_map"][vs.id]
+
+
+def test_duplicate_safety_net_flags_unremapped_ref(stores, monkeypatch):
+    """If a reference somehow isn't remapped, the post-clone safety net reports
+    it in `warnings` rather than silently leaving two pipelines sharing a node."""
+    css, _vss = stores
+    b = css.create_source(name="B", source_type="single_color", colors=[[1, 2, 3]])
+    a = css.create_source(name="A", source_type="composite", layers=[_layer(b.id)])
+    # Force remap to a no-op so the clone keeps pointing at the original in-set id.
+    monkeypatch.setattr("ledgrab.api.routes.graph.remap_refs", lambda *a, **k: 0)
+    res = _duplicate_subgraph([a.id, b.id], " (copy)")
+    assert any(w["id"] == res["id_map"][a.id] for w in res["warnings"])
+
+
+def test_duplicate_value_source(stores):
+    _css, vss = stores
+    v = vss.create_source(name="V", source_type="static", value=0.5)
+    res = _duplicate_subgraph([v.id], " (copy)")
+    assert list(res["id_map"]) == [v.id]
+    new = vss.get(res["id_map"][v.id])
+    assert new.id != v.id
+    assert new.name == "V (copy)"
+    assert getattr(new, "value", None) == 0.5
+
+
+def test_duplicate_skips_non_duplicable_ids(stores):
+    _css, vss = stores
+    v = vss.create_source(name="V", source_type="static", value=0.5)
+    res = _duplicate_subgraph([v.id, "dev_external", "bogus"], " (copy)")
+    assert list(res["id_map"]) == [v.id]
+    assert {s["id"] for s in res["skipped"]} == {"dev_external", "bogus"}
+
+
+def test_duplicate_name_collision_is_suffixed(stores):
+    _css, vss = stores
+    v = vss.create_source(name="V", source_type="static", value=0.5)
+    vss.create_source(name="V (copy)", source_type="static", value=0.1)  # occupy the obvious name
+    res = _duplicate_subgraph([v.id], " (copy)")
+    new = vss.get(res["id_map"][v.id])
+    assert new.name == "V (copy) 2"
+
+
+def test_clone_allowlist_invariant():
+    """Only explicitly-flagged (secret-free) stores are cloneable; the base
+    default is off so a new store is never cloneable by accident."""
+    from ledgrab.storage.base_sqlite_store import BaseSqliteStore
+
+    assert BaseSqliteStore._cloneable is False
+    assert ColorStripStore._cloneable is True
+    assert ValueSourceStore._cloneable is True
+
+
+def test_clone_refuses_non_cloneable_store(stores, monkeypatch):
+    """clone() refuses stores not on the allowlist (defence-in-depth even though
+    the duplicate endpoint already restricts to the safe kinds)."""
+    css, _vss = stores
+    src = css.create_source(name="X", source_type="single_color", colors=[[1, 1, 1]])
+    monkeypatch.setattr(type(css), "_cloneable", False)
+    with pytest.raises(NotImplementedError):
+        css.clone(src.id, "X (copy)")

server/tests/api/test_graph_schema.py

@@ -4,6 +4,10 @@ These exercise reference extraction, topology building, dependents, cycle and
 dangling-reference detection without booting the app or any store.
 """
 
+import json
+import re
+from dataclasses import dataclass, field
+
 from ledgrab.api.graph_schema import (
     CONNECTION_SCHEMA,
     ENTITY_KINDS,
@@ -11,7 +15,11 @@ from ledgrab.api.graph_schema import (
     detect_cycles,
     extract_refs,
     find_dependents,
+    graph_field_roots,
+    is_editable,
+    remap_refs,
     schema_for_kind,
+    serialize_entity_for_graph,
     validate_connection,
     would_create_cycle,
 )
@@ -60,6 +68,56 @@ def test_extract_refs_nested_object_none_is_safe():
     ) == ["pt_1"]
 
 
+# ── remap_refs (write-twin of extract_refs) ──────────────────────────────────
+
+
+def test_remap_refs_top_level():
+    e = {"device_id": "a"}
+    assert remap_refs(e, "device_id", {"a": "b"}) == 1
+    assert e["device_id"] == "b"
+
+
+def test_remap_refs_leaves_unmapped_ids_untouched():
+    e = {"device_id": "external"}
+    assert remap_refs(e, "device_id", {"a": "b"}) == 0
+    assert e["device_id"] == "external"  # shared dependency outside the set
+
+
+def test_remap_refs_bindable_bound():
+    e = {"brightness": {"value": 1.0, "source_id": "a"}}
+    assert remap_refs(e, "brightness.source_id", {"a": "b"}) == 1
+    assert e["brightness"] == {"value": 1.0, "source_id": "b"}
+
+
+def test_remap_refs_unbound_bindable_is_safe():
+    e = {"brightness": 0.5}  # plain number, no binding
+    assert remap_refs(e, "brightness.source_id", {"a": "b"}) == 0
+    assert e["brightness"] == 0.5
+
+
+def test_remap_refs_list_field_only_mapped_elements():
+    e = {"layers": [{"source_id": "a"}, {"source_id": "external"}, {"source_id": "c"}]}
+    assert remap_refs(e, "layers[].source_id", {"a": "b", "c": "d"}) == 2
+    assert [layer["source_id"] for layer in e["layers"]] == ["b", "external", "d"]
+
+
+def test_remap_refs_deep_object_then_list():
+    e = {"calibration": {"lines": [{"picture_source_id": "p1"}, {"picture_source_id": "p2"}]}}
+    assert remap_refs(e, "calibration.lines[].picture_source_id", {"p1": "q1"}) == 1
+    assert [ln["picture_source_id"] for ln in e["calibration"]["lines"]] == ["q1", "p2"]
+
+
+def test_remap_refs_missing_keys_are_safe():
+    assert remap_refs({}, "layers[].source_id", {"a": "b"}) == 0
+    assert remap_refs({"layers": None}, "layers[].source_id", {"a": "b"}) == 0
+
+
+def test_remap_refs_round_trips_with_extract_refs():
+    e = {"layers": [{"source_id": "a"}, {"source_id": "a"}]}
+    remap_refs(e, "layers[].source_id", {"a": "b"})
+    assert extract_refs(e, "layers[].source_id") == ["b", "b"]
+
+
 # ── registry consistency ─────────────────────────────────────────────────────
 
 
@@ -249,7 +307,79 @@ def test_validate_connection_rejects_list_field():
         entities, "color_strip_source", "css_1", "layers[].source_id", "css_2"
     )
     assert ok is False
-    assert "List connection" in err
+    assert "not editable" in err
+
+
+def test_validate_connection_rejects_color_bindable():
+    # Colour bindings are structurally bindable but not graph-editable (a value
+    # source can't drive a colour).
+    entities = {
+        "color_strip_source": [
+            {"id": "css_1", "name": "X", "source_type": "single_color", "color": [255, 0, 0]}
+        ],
+        "value_source": [{"id": "vs_1", "name": "V", "source_type": "static"}],
+    }
+    ok, err = validate_connection(
+        entities, "color_strip_source", "css_1", "color.source_id", "vs_1"
+    )
+    assert ok is False
+    assert "not editable" in err
+
+
+@dataclass
+class _FakeRule:
+    token: str = "SUPER_SECRET_WEBHOOK_TOKEN"
+
+
+@dataclass
+class _FakeAutomation:
+    id: str = "auto_1"
+    name: str = "A"
+    enabled: bool = True
+    scene_preset_id: str = "sp_1"
+    rules: list = field(default_factory=lambda: [_FakeRule()])
+
+
+# Keys that must NEVER appear in the /graph projection allowlist.
+_SECRET_KEY_RE = re.compile(
+    r"token|password|secret|credential|api[_-]?key|_key$|username|\burl\b|\bhost\b", re.I
+)
+
+
+def test_projection_roots_never_expose_secrets():
+    # The /graph projection (graph_field_roots) is the leak boundary. Assert no
+    # kind's allowlist contains a secret-bearing key — locks the boundary against
+    # future schema drift (a new reference field whose root looks like a secret).
+    for kind in ENTITY_KINDS:
+        for root in graph_field_roots(kind):
+            assert not _SECRET_KEY_RE.search(
+                root
+            ), f"{kind}: projected root {root!r} looks secret-bearing"
+
+
+def test_serialize_entity_for_graph_drops_secrets():
+    # The graph projection must strip everything except id/name/type + reference
+    # roots — a deep asdict would otherwise leak the webhook token (a real,
+    # auth-equivalent secret) in the /graph response.
+    projected = serialize_entity_for_graph("automation", _FakeAutomation())
+    assert projected["id"] == "auto_1"
+    assert projected["name"] == "A"
+    assert projected["scene_preset_id"] == "sp_1"  # reference root kept
+    assert "rules" not in projected  # non-reference field dropped
+    assert "enabled" not in projected
+    assert "SUPER_SECRET_WEBHOOK_TOKEN" not in json.dumps(projected)
+
+
+def test_is_editable_classifies_fields():
+    by_field = {(c.target_kind, c.field): c for c in CONNECTION_SCHEMA}
+    # Top-level reference and single-level BindableFloat → editable.
+    assert is_editable(by_field[("output_target", "device_id")])
+    assert is_editable(by_field[("color_strip_source", "brightness.source_id")])
+    assert is_editable(by_field[("output_target", "transition.source_id")])
+    # Colour binding, list slot, and double-nested → NOT editable.
+    assert not is_editable(by_field[("color_strip_source", "color.source_id")])
+    assert not is_editable(by_field[("color_strip_source", "layers[].source_id")])
+    assert not is_editable(by_field[("output_target", "settings.brightness.source_id")])
 
 
 def test_validate_connection_rejects_cycle():

server/tests/api/test_graph_wiring_contract.py

@@ -0,0 +1,159 @@
+"""Contract tests for graph drag-to-wire writes.
+
+The graph editor's ``updateConnection()`` performs a *partial* PUT for a single
+dragged edge: it sends only the reference (or bindable) field being wired. Five
+entity kinds have ``Body(discriminator=...)`` PUT routes, so such a partial body
+is rejected with a 422 unless it also echoes the entity's subtype
+(``source_type`` / ``stream_type`` / ``target_type``). ``updateConnection()`` now
+reads the target's subtype back and includes it.
+
+These tests lock in that contract from the backend side: each ``(kind, field)``
+pair the frontend ``CONNECTION_MAP`` drag-edits must validate as a minimal
+``{discriminator, field}`` body — and must be rejected without the discriminator
+(the exact failure that silently broke wiring). If a future schema change makes
+one of these fields required-with-siblings, or drops a subtype, these tests fail
+and flag that graph wiring will break.
+"""
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from ledgrab.api.schemas.audio_sources import AudioSourceUpdate
+from ledgrab.api.schemas.color_strip_sources import ColorStripSourceUpdate
+from ledgrab.api.schemas.output_targets import OutputTargetUpdate
+from ledgrab.api.schemas.picture_sources import PictureSourceUpdate
+from ledgrab.api.schemas.value_sources import ValueSourceUpdate
+
+# Each row mirrors one drag-editable (target_kind, field) pair from the frontend
+# CONNECTION_MAP, paired with a real subtype tag that owns that field and the
+# body shape updateConnection() sends: a flat ref id, or a bindable
+# ``{parent: {source_id}}`` slot (here keyed by the parent field root).
+# (kind, update_union, discriminator_field, subtype_tag, body_field, sample_value)
+_WIRING_WRITES = [
+    ("value_source", ValueSourceUpdate, "source_type", "audio", "audio_source_id", "as_1"),
+    (
+        "value_source",
+        ValueSourceUpdate,
+        "source_type",
+        "adaptive_scene",
+        "picture_source_id",
+        "ps_1",
+    ),
+    ("value_source", ValueSourceUpdate, "source_type", "gradient_map", "value_source_id", "vs_1"),
+    (
+        "value_source",
+        ValueSourceUpdate,
+        "source_type",
+        "css_extract",
+        "color_strip_source_id",
+        "css_1",
+    ),
+    (
+        "color_strip_source",
+        ColorStripSourceUpdate,
+        "source_type",
+        "picture",
+        "picture_source_id",
+        "ps_1",
+    ),
+    (
+        "color_strip_source",
+        ColorStripSourceUpdate,
+        "source_type",
+        "audio",
+        "audio_source_id",
+        "as_1",
+    ),
+    (
+        "color_strip_source",
+        ColorStripSourceUpdate,
+        "source_type",
+        "processed",
+        "input_source_id",
+        "css_2",
+    ),
+    (
+        "color_strip_source",
+        ColorStripSourceUpdate,
+        "source_type",
+        "processed",
+        "processing_template_id",
+        "cspt_1",
+    ),
+    # bindable BindableFloat slot — body is {<parent>: {source_id}}
+    (
+        "color_strip_source",
+        ColorStripSourceUpdate,
+        "source_type",
+        "audio",
+        "smoothing",
+        {"source_id": "vs_1"},
+    ),
+    ("audio_source", AudioSourceUpdate, "source_type", "capture", "audio_template_id", "at_1"),
+    ("audio_source", AudioSourceUpdate, "source_type", "processed", "audio_source_id", "as_2"),
+    ("picture_source", PictureSourceUpdate, "stream_type", "raw", "capture_template_id", "ct_1"),
+    ("picture_source", PictureSourceUpdate, "stream_type", "processed", "source_stream_id", "ps_2"),
+    (
+        "picture_source",
+        PictureSourceUpdate,
+        "stream_type",
+        "processed",
+        "postprocessing_template_id",
+        "ppt_1",
+    ),
+    ("output_target", OutputTargetUpdate, "target_type", "led", "device_id", "dev_1"),
+    ("output_target", OutputTargetUpdate, "target_type", "led", "color_strip_source_id", "css_1"),
+    # bindable slots on output targets
+    (
+        "output_target",
+        OutputTargetUpdate,
+        "target_type",
+        "led",
+        "brightness",
+        {"source_id": "vs_1"},
+    ),
+    (
+        "output_target",
+        OutputTargetUpdate,
+        "target_type",
+        "ha_light",
+        "transition",
+        {"source_id": "vs_1"},
+    ),
+]
+
+_IDS = [f"{kind}.{field}[{tag}]" for kind, _u, _d, tag, field, _v in _WIRING_WRITES]
+
+
+@pytest.mark.parametrize("kind,union,disc,tag,field,value", _WIRING_WRITES, ids=_IDS)
+def test_partial_wiring_put_validates_with_discriminator(kind, union, disc, tag, field, value):
+    """A single dragged wiring edit validates when the subtype is echoed.
+
+    This is exactly what updateConnection() now sends; if it fails, drag-to-wire
+    for ``kind.field`` is broken.
+    """
+    model = TypeAdapter(union).validate_python({disc: tag, field: value})
+    assert getattr(model, disc) == tag
+
+
+@pytest.mark.parametrize("kind,union,disc,tag,field,value", _WIRING_WRITES, ids=_IDS)
+def test_partial_wiring_put_rejected_without_discriminator(kind, union, disc, tag, field, value):
+    """Without the discriminator the same body is rejected.
+
+    This is the 422 that silently broke drag-to-wire before updateConnection()
+    echoed the subtype — guarding against anyone "simplifying" that away.
+    """
+    with pytest.raises(ValidationError):
+        TypeAdapter(union).validate_python({field: value})
+
+
+@pytest.mark.parametrize("kind,union,disc,tag,field,value", _WIRING_WRITES, ids=_IDS)
+def test_partial_wiring_detach_validates_with_discriminator(kind, union, disc, tag, field, value):
+    """Detach (clearing a slot) goes through the same partial-PUT path and must
+    also validate with the subtype echoed: ``{field: ""}`` for a flat reference,
+    ``{parent: {source_id: ""}}`` for a bindable slot — exactly what
+    ``detachConnection()`` -> ``updateConnection(..., "")`` sends.
+    """
+    cleared = {"source_id": ""} if isinstance(value, dict) else ""
+    model = TypeAdapter(union).validate_python({disc: tag, field: cleared})
+    assert getattr(model, disc) == tag

server/tests/core/processing/test_os_notification_listener_android.py

@@ -0,0 +1,237 @@
+"""Tests for the Android push-based notification backend.
+
+These run on desktop CI (no Android device needed): ``is_android`` is
+monkeypatched and the app label is pushed directly into the module-level
+``push_notification`` receiver, exactly as the Kotlin
+``NotificationListenerService`` would across the Chaquopy bridge.
+
+Isolation (critical): the listener keeps process-global state
+(``_android_target``, ``_instance``) and persists history to a hardcoded
+``data/notification_history.json``. Every test resets those globals and
+repoints ``_HISTORY_FILE`` to ``tmp_path`` so the suite never leaks state
+between tests or clobbers the real repo data file.
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+
+import ledgrab.core.processing.os_notification_listener as nl
+from ledgrab.storage.color_strip_source import NotificationColorStripSource
+
+PLATFORM_MOD = "ledgrab.utils.platform"
+
+
+# ---------------------------------------------------------------------------
+# Test doubles
+# ---------------------------------------------------------------------------
+
+
+class _FakeStream:
+    """Stub NotificationColorStripStream — records fire() calls."""
+
+    def __init__(self, accept: bool = True):
+        self._accept = accept
+        self.fired_with: list = []
+
+    def fire(self, app_name=None) -> bool:
+        self.fired_with.append(app_name)
+        return self._accept
+
+
+class _FakeStore:
+    def __init__(self, sources):
+        self._sources = sources
+
+    def get_all_sources(self):
+        return list(self._sources)
+
+
+class _FakeStreamManager:
+    def __init__(self, streams):
+        self._streams = streams
+
+    def get_streams_by_source_id(self, source_id):
+        return list(self._streams)
+
+
+def _notif_source(
+    *, source_id: str = "css_test", os_listener: bool = True
+) -> NotificationColorStripSource:
+    now = datetime.now(timezone.utc)
+    return NotificationColorStripSource.create_from_kwargs(
+        id=source_id,
+        name="Test Notification Source",
+        source_type="notification",
+        created_at=now,
+        updated_at=now,
+        os_listener=os_listener,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fixtures — module-global + disk isolation
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def nl_mod(monkeypatch, tmp_path):
+    """Reset module globals and repoint the history file to tmp_path.
+
+    ``monkeypatch.setattr`` auto-restores originals on teardown, so even though
+    ``start()``/``stop()`` rebind ``_android_target`` and ``_instance`` during a
+    test, the globals are returned to their pre-test values afterward — no
+    cross-test leakage and no write to the real repo ``data/`` dir.
+    """
+    monkeypatch.setattr(nl, "_android_target", None)
+    monkeypatch.setattr(nl, "_instance", None)
+    monkeypatch.setattr(nl, "_HISTORY_FILE", tmp_path / "notification_history.json")
+    return nl
+
+
+# ---------------------------------------------------------------------------
+# _AndroidBackend.probe()
+# ---------------------------------------------------------------------------
+
+
+def test_probe_true_on_android(nl_mod, monkeypatch):
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: True)
+    assert nl_mod._AndroidBackend.probe() is True
+
+
+def test_probe_false_on_desktop(nl_mod, monkeypatch):
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: False)
+    assert nl_mod._AndroidBackend.probe() is False
+
+
+# ---------------------------------------------------------------------------
+# push_notification() routing contract
+# ---------------------------------------------------------------------------
+
+
+def test_push_is_noop_before_start(nl_mod):
+    # _android_target is None → no callback, no exception.
+    nl_mod.push_notification("Telegram")  # must not raise
+
+
+def test_push_routes_after_start_and_stops_after_stop(nl_mod):
+    received: list = []
+    backend = nl_mod._AndroidBackend(on_notification=received.append)
+
+    backend.start()
+    nl_mod.push_notification("Telegram")
+    assert received == ["Telegram"]
+
+    backend.stop()
+    nl_mod.push_notification("Signal")  # no-op after stop
+    assert received == ["Telegram"]
+
+
+def test_push_swallows_callback_exception(nl_mod):
+    def boom(_app):
+        raise RuntimeError("callback exploded")
+
+    nl_mod._AndroidBackend(on_notification=boom).start()
+    # JNI entry point must never propagate — would crash the bound service.
+    nl_mod.push_notification("X")
+
+
+# ---------------------------------------------------------------------------
+# Integration — start() selects Android, push fires the stream + records history
+# ---------------------------------------------------------------------------
+
+
+def test_android_selected_push_fires_stream_and_records_history(nl_mod, monkeypatch, tmp_path):
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: True)
+    stream = _FakeStream(accept=True)
+    listener = nl_mod.OsNotificationListener(
+        _FakeStore([_notif_source(os_listener=True)]),
+        _FakeStreamManager([stream]),
+    )
+
+    listener.start()
+    assert listener.available is True  # flips True on backend selection, not on push
+
+    nl_mod.push_notification("Telegram")
+
+    assert stream.fired_with == ["Telegram"]
+    assert listener.recent_history[0]["app"] == "Telegram"
+    assert listener.recent_history[0]["fired"] == 1
+    # history written under tmp_path — never the repo data/ dir
+    assert nl_mod._HISTORY_FILE.exists()
+    assert nl_mod._HISTORY_FILE.parent == tmp_path
+
+    listener.stop()
+
+
+def test_push_with_none_app_name_is_recorded(nl_mod, monkeypatch):
+    # The Windows (_extract_app_name) and Linux D-Bus paths can yield None;
+    # the Android path falls back to the package name, but None must still be
+    # handled end-to-end without raising.
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: True)
+    stream = _FakeStream(accept=True)
+    listener = nl_mod.OsNotificationListener(
+        _FakeStore([_notif_source(os_listener=True)]),
+        _FakeStreamManager([stream]),
+    )
+
+    listener.start()
+    nl_mod.push_notification(None)
+
+    assert stream.fired_with == [None]
+    assert listener.recent_history[0]["app"] is None
+    listener.stop()
+
+
+def test_get_os_notification_listener_tracks_started_instance(nl_mod, monkeypatch):
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: True)
+    assert nl_mod.get_os_notification_listener() is None
+
+    listener = nl_mod.OsNotificationListener(_FakeStore([]), _FakeStreamManager([]))
+    listener.start()
+    assert nl_mod.get_os_notification_listener() is listener
+    listener.stop()
+
+
+def test_source_with_os_listener_off_does_not_fire(nl_mod, monkeypatch):
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: True)
+    stream = _FakeStream()
+    listener = nl_mod.OsNotificationListener(
+        _FakeStore([_notif_source(os_listener=False)]),
+        _FakeStreamManager([stream]),
+    )
+
+    listener.start()
+    nl_mod.push_notification("Telegram")
+
+    assert stream.fired_with == []  # os_listener=False → skipped
+    listener.stop()
+
+
+# ---------------------------------------------------------------------------
+# Desktop regression — the probe-order change must not alter desktop selection
+# ---------------------------------------------------------------------------
+
+
+def test_android_probe_false_on_real_desktop(nl_mod, monkeypatch):
+    # With is_android() False, the new first-in-tuple backend must not be selectable.
+    monkeypatch.setattr(f"{PLATFORM_MOD}.is_android", lambda: False)
+    assert nl_mod._AndroidBackend.probe() is False
+
+
+def test_desktop_selection_unchanged_windows_wins(nl_mod, monkeypatch):
+    # Deterministically control probes and stub start() so no real polling thread spawns.
+    # Order under test is (_AndroidBackend, _WindowsBackend, _LinuxBackend): Android skipped,
+    # Windows is the first True → it must be the selected backend, exactly as before.
+    monkeypatch.setattr(nl_mod._AndroidBackend, "probe", staticmethod(lambda: False))
+    monkeypatch.setattr(nl_mod._WindowsBackend, "probe", staticmethod(lambda: True))
+    monkeypatch.setattr(nl_mod._LinuxBackend, "probe", staticmethod(lambda: False))
+    started: list = []
+    monkeypatch.setattr(nl_mod._WindowsBackend, "start", lambda self: started.append("win"))
+
+    listener = nl_mod.OsNotificationListener(_FakeStore([]), _FakeStreamManager([]))
+    listener.start()
+
+    assert listener.available is True
+    assert isinstance(listener._backend, nl_mod._WindowsBackend)
+    assert started == ["win"]

server/tests/core/processing/test_template_value_stream.py

@@ -0,0 +1,231 @@
+"""Tests for TemplateValueStream (the Jinja combinator runtime)."""
+
+from collections import defaultdict
+from datetime import datetime, timezone
+
+import pytest
+
+from ledgrab.core.processing.value_stream import (
+    TemplateValueStream,
+    ValueStreamManager,
+)
+from ledgrab.storage.value_source import TemplateValueSource
+
+
+# --- Fakes for precise control over input values / raw -----------------------
+
+
+class _FakeStream:
+    _NO_RAW = object()
+
+    def __init__(self, value, raw=_NO_RAW):
+        self._value = value
+        self._raw = raw
+
+    def get_value(self):
+        return self._value
+
+    # get_raw_value only exists when a raw value was provided
+    def __getattr__(self, name):
+        if name == "get_raw_value" and self._raw is not _FakeStream._NO_RAW:
+            return lambda: self._raw
+        raise AttributeError(name)
+
+
+class _FakeVSM:
+    def __init__(self, streams):
+        self._streams = streams  # id -> _FakeStream
+        self.refcounts = defaultdict(int)
+
+    def acquire(self, vs_id):
+        self.refcounts[vs_id] += 1
+        return self._streams[vs_id]
+
+    def release(self, vs_id):
+        self.refcounts[vs_id] -= 1
+
+
+def _inputs(*pairs):
+    return [{"name": n, "value_source_id": i} for n, i in pairs]
+
+
+def _make(template, inputs, streams, default_value=0.0, eval_interval=None):
+    vsm = _FakeVSM(streams)
+    stream = TemplateValueStream(
+        template=template,
+        inputs=inputs,
+        default_value=default_value,
+        eval_interval=eval_interval,
+        value_stream_manager=vsm,
+    )
+    stream.start()
+    return stream, vsm
+
+
+class TestEvaluation:
+    def test_eval_with_inputs(self):
+        stream, vsm = _make("min(a * 2, 1)", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.3)})
+        assert vsm.refcounts["vs_a"] == 1
+        assert stream.get_value() == pytest.approx(0.6)
+
+    def test_clamps_out_of_range(self):
+        stream, _ = _make("a * 10", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.5)})
+        assert stream.get_value() == 1.0  # 5.0 clamped
+
+    def test_two_inputs(self):
+        stream, _ = _make(
+            "(a + b) / 2",
+            _inputs(("a", "vs_a"), ("b", "vs_b")),
+            {"vs_a": _FakeStream(0.2), "vs_b": _FakeStream(0.8)},
+        )
+        assert stream.get_value() == pytest.approx(0.5)
+
+    def test_shared_id_single_ref(self):
+        # Two variables bound to the same source share one acquisition.
+        stream, vsm = _make(
+            "min(a + b, 1)",
+            _inputs(("a", "vs_x"), ("b", "vs_x")),
+            {"vs_x": _FakeStream(0.3)},
+        )
+        assert vsm.refcounts["vs_x"] == 1
+        assert stream.get_value() == pytest.approx(0.6)
+
+
+class TestErrorHandling:
+    def test_div_by_zero_returns_default(self):
+        stream, _ = _make(
+            "a / 0", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.5)}, default_value=0.25
+        )
+        assert stream.get_value() == 0.25
+
+    def test_missing_variable_returns_default(self):
+        # template references 'b' but only 'a' is bound
+        stream, _ = _make(
+            "a + b", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.5)}, default_value=0.1
+        )
+        assert stream.get_value() == 0.1
+
+    def test_nan_returns_default(self):
+        stream, _ = _make(
+            "a - a", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(float("inf"))}, default_value=0.3
+        )
+        # inf - inf = nan -> default
+        assert stream.get_value() == 0.3
+
+    def test_invalid_template_uses_default(self):
+        stream, _ = _make(
+            "a +", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.5)}, default_value=0.42
+        )
+        assert stream.get_value() == 0.42
+
+
+class TestRawExposure:
+    def test_raw_present_when_stream_exposes_it(self):
+        stream, _ = _make(
+            "raw['t'] / 100",
+            _inputs(("t", "vs_t")),
+            {"vs_t": _FakeStream(0.5, raw=42.0)},
+        )
+        assert stream.get_value() == pytest.approx(0.42)
+
+    def test_raw_absent_without_getter(self):
+        # input stream has no get_raw_value -> raw['t'] -> None -> error -> default
+        stream, _ = _make(
+            "raw['t'] / 100",
+            _inputs(("t", "vs_t")),
+            {"vs_t": _FakeStream(0.5)},
+            default_value=0.2,
+        )
+        assert stream.get_value() == 0.2
+
+    def test_non_numeric_raw_is_dropped(self):
+        # raw value is a string -> never crosses into sandbox -> raw['t'] absent
+        stream, _ = _make(
+            "raw['t'] / 100",
+            _inputs(("t", "vs_t")),
+            {"vs_t": _FakeStream(0.5, raw="playing")},
+            default_value=0.15,
+        )
+        assert stream.get_value() == 0.15
+
+
+class TestLifecycle:
+    def test_stop_releases_all(self):
+        stream, vsm = _make(
+            "min(a + b, 1)",
+            _inputs(("a", "vs_a"), ("b", "vs_b")),
+            {"vs_a": _FakeStream(0.1), "vs_b": _FakeStream(0.2)},
+        )
+        stream.stop()
+        assert vsm.refcounts["vs_a"] == 0
+        assert vsm.refcounts["vs_b"] == 0
+
+    def test_eval_interval_caches(self):
+        backing = _FakeStream(0.2)
+        stream, _ = _make("a", _inputs(("a", "vs_a")), {"vs_a": backing}, eval_interval=3600.0)
+        first = stream.get_value()
+        backing._value = 0.9  # change the live input
+        # Cached within the interval -> still the first value.
+        assert stream.get_value() == pytest.approx(first)
+
+
+class TestHotUpdate:
+    def test_swap_input_releases_old_acquires_new(self):
+        stream, vsm = _make(
+            "a", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.1), "vs_b": _FakeStream(0.9)}
+        )
+        assert vsm.refcounts["vs_a"] == 1
+        new_src = TemplateValueSource(
+            id="t1",
+            name="t",
+            source_type="template",
+            created_at=datetime.now(timezone.utc),
+            updated_at=datetime.now(timezone.utc),
+            template="a",
+            inputs=_inputs(("a", "vs_b")),
+            default_value=0.0,
+        )
+        stream.update_source(new_src)
+        assert vsm.refcounts["vs_a"] == 0  # old released
+        assert vsm.refcounts["vs_b"] == 1  # new acquired
+        assert stream.get_value() == pytest.approx(0.9)
+
+    def test_rename_keeps_same_source(self):
+        stream, vsm = _make("a", _inputs(("a", "vs_a")), {"vs_a": _FakeStream(0.7)})
+        renamed = TemplateValueSource(
+            id="t1",
+            name="t",
+            source_type="template",
+            created_at=datetime.now(timezone.utc),
+            updated_at=datetime.now(timezone.utc),
+            template="b",  # variable renamed a -> b, same source id
+            inputs=_inputs(("b", "vs_a")),
+            default_value=0.0,
+        )
+        stream.update_source(renamed)
+        assert vsm.refcounts["vs_a"] == 1  # not re-acquired (unchanged id)
+        assert stream.get_value() == pytest.approx(0.7)
+
+
+class TestAcquireDepthBackstop:
+    def test_self_reference_does_not_overflow(self):
+        """A cycle that bypassed storage validation must not stack-overflow."""
+        now = datetime.now(timezone.utc)
+        src = TemplateValueSource(
+            id="vs_cycle",
+            name="cycle",
+            source_type="template",
+            created_at=now,
+            updated_at=now,
+            template="x",
+            inputs=_inputs(("x", "vs_cycle")),
+            default_value=0.0,
+        )
+
+        class _CycleStore:
+            def get_source(self, vs_id):
+                return src
+
+        manager = ValueStreamManager(value_source_store=_CycleStore())
+        stream = manager.acquire("vs_cycle")  # must terminate, not recurse forever
+        assert isinstance(stream.get_value(), float)

server/tests/core/processing/test_value_source_normalize.py

@@ -0,0 +1,380 @@
+"""Tests for the optional-normalization feature on magnitude value sources.
+
+Covers, for HA / HTTP / system_metrics / game_event:
+  * the ``normalize`` flag round-trips through to_dict/from_dict and defaults to
+    True for old rows that predate the field,
+  * ``normalize=False`` makes get_value() a finite-safe clamp passthrough while
+    get_value() stays in [0, 1] (the normalized scalar-bus contract), and
+  * the raw magnitude remains available via get_raw_value() (added to
+    game_event, which had no raw channel before).
+Plus a unit test for the shared finite-safe ``clamp01`` helper.
+"""
+
+import math
+
+import pytest
+
+from ledgrab.core.game_integration.event_bus import GameEventBus
+from ledgrab.core.game_integration.events import GameEvent
+from ledgrab.core.processing.value_kinds import ValueStreamDeps, build_stream
+from ledgrab.core.processing.value_stream import (
+    HAEntityValueStream,
+    HTTPValueStream,
+    SystemMetricsValueStream,
+)
+from ledgrab.core.value_sources.game_event_value_source import GameEventValueStream
+from ledgrab.storage.value_source import ValueSource
+from ledgrab.utils import clamp01
+
+
+# ---------------------------------------------------------------------------
+# clamp01 finite-safe helper
+# ---------------------------------------------------------------------------
+
+
+class TestClamp01:
+    def test_in_range_passthrough(self):
+        assert clamp01(0.0) == 0.0
+        assert clamp01(0.42) == pytest.approx(0.42)
+        assert clamp01(1.0) == 1.0
+
+    def test_out_of_range_clamped(self):
+        assert clamp01(-2.5) == 0.0
+        assert clamp01(5.0) == 1.0
+
+    def test_non_finite_rejected_to_default(self):
+        assert clamp01(float("nan")) == 0.0
+        assert clamp01(float("inf")) == 0.0
+        assert clamp01(float("-inf")) == 0.0
+        # custom default is honoured
+        assert clamp01(float("nan"), default=0.5) == 0.5
+
+
+# ---------------------------------------------------------------------------
+# Round-trip persistence of the normalize flag
+# ---------------------------------------------------------------------------
+
+
+def _base(source_type: str, **extra) -> dict:
+    return {
+        "id": f"vs_{source_type}",
+        "name": source_type,
+        "source_type": source_type,
+        "created_at": "2025-01-01T00:00:00+00:00",
+        "updated_at": "2025-01-01T00:00:00+00:00",
+        **extra,
+    }
+
+
+class TestNormalizeRoundTrip:
+    @pytest.mark.parametrize(
+        "source_type,extra",
+        [
+            ("ha_entity", {"ha_source_id": "ha1", "entity_id": "sensor.temp"}),
+            ("http", {"http_endpoint_id": "ep1"}),
+            ("system_metrics", {"metric": "cpu_load"}),
+            ("game_event", {}),
+        ],
+    )
+    def test_normalize_false_round_trips(self, source_type, extra):
+        src = ValueSource.from_dict(_base(source_type, normalize=False, **extra))
+        assert src.normalize is False
+        assert src.to_dict()["normalize"] is False
+        restored = ValueSource.from_dict(src.to_dict())
+        assert restored.normalize is False
+
+    @pytest.mark.parametrize(
+        "source_type,extra",
+        [
+            ("ha_entity", {"ha_source_id": "ha1", "entity_id": "sensor.temp"}),
+            ("http", {"http_endpoint_id": "ep1"}),
+            ("system_metrics", {"metric": "cpu_load"}),
+            ("game_event", {}),
+        ],
+    )
+    def test_missing_key_defaults_true(self, source_type, extra):
+        """An old row written before the field existed reads back normalize=True."""
+        src = ValueSource.from_dict(_base(source_type, **extra))
+        assert src.normalize is True
+        assert src.to_dict()["normalize"] is True
+
+
+# ---------------------------------------------------------------------------
+# HTTP stream — clamp passthrough + verbatim raw
+# ---------------------------------------------------------------------------
+
+
+def _http(normalize: bool, raw) -> HTTPValueStream:
+    s = HTTPValueStream(
+        endpoint_id="ep",
+        json_path="",
+        interval_s=60,
+        min_value=0.0,
+        max_value=100.0,
+        smoothing=0.0,
+        normalize=normalize,
+    )
+    s._raw_value = raw  # bypass the poll loop; exercise get_value() directly
+    return s
+
+
+class TestHttpNormalize:
+    def test_normalize_true_rescales(self):
+        assert _http(True, 50.0).get_value() == pytest.approx(0.5)
+
+    def test_normalize_false_clamps_in_range(self):
+        assert _http(False, 0.7).get_value() == pytest.approx(0.7)
+
+    def test_normalize_false_clamps_out_of_range(self):
+        assert _http(False, 5.0).get_value() == 1.0
+        assert _http(False, -3.0).get_value() == 0.0
+
+    def test_normalize_false_non_finite_safe(self):
+        assert _http(False, float("inf")).get_value() == 0.0
+        assert _http(False, float("nan")).get_value() == 0.0
+
+    def test_non_numeric_raw_keeps_get_value_numeric_and_raw_verbatim(self):
+        s = _http(False, "playing")
+        assert s.get_value() == 0.0  # float("playing") fails -> safe fallback
+        assert s.get_raw_value() == "playing"  # verbatim for automations/templates
+
+
+# ---------------------------------------------------------------------------
+# HA stream — clamp passthrough via a minimal fake HA manager
+# ---------------------------------------------------------------------------
+
+
+class _FakeState:
+    def __init__(self, state, attributes=None):
+        self.state = state
+        self.attributes = attributes or {}
+
+
+class _FakeHA:
+    def __init__(self, state):
+        self._state = state
+
+    def get_state(self, _source_id, _entity_id):
+        return self._state
+
+
+def _ha(normalize: bool, state_value: str) -> HAEntityValueStream:
+    return HAEntityValueStream(
+        ha_source_id="ha1",
+        entity_id="sensor.temp",
+        attribute="",
+        min_ha_value=0.0,
+        max_ha_value=100.0,
+        smoothing=0.0,
+        normalize=normalize,
+        ha_manager=_FakeHA(_FakeState(state_value)),
+    )
+
+
+class TestHaNormalize:
+    def test_normalize_true_rescales(self):
+        assert _ha(True, "50").get_value() == pytest.approx(0.5)
+
+    def test_normalize_false_clamps_and_keeps_raw(self):
+        s = _ha(False, "21.5")  # e.g. °C — out of [0,1]
+        assert s.get_value() == 1.0  # clamped
+        assert s.get_raw_value() == pytest.approx(21.5)  # un-clamped magnitude
+
+    def test_normalize_false_in_range_fraction(self):
+        s = _ha(False, "0.3")
+        assert s.get_value() == pytest.approx(0.3)
+
+
+# ---------------------------------------------------------------------------
+# system_metrics stream — clamp passthrough (raw reader monkeypatched)
+# ---------------------------------------------------------------------------
+
+
+class TestSystemMetricsNormalize:
+    def test_normalize_false_clamps_and_keeps_raw(self):
+        s = SystemMetricsValueStream(
+            metric="cpu_load", min_value=0.0, max_value=100.0, normalize=False
+        )
+        s._read_metric = lambda: 65.0  # type: ignore[method-assign]
+        assert s.get_value() == 1.0  # 65 clamped to 1.0
+        assert s.get_raw_value() == pytest.approx(65.0)
+
+    def test_normalize_false_in_range_fraction(self):
+        s = SystemMetricsValueStream(
+            metric="cpu_load", min_value=0.0, max_value=100.0, normalize=False
+        )
+        s._read_metric = lambda: 0.25  # type: ignore[method-assign]
+        assert s.get_value() == pytest.approx(0.25)
+
+
+# ---------------------------------------------------------------------------
+# game_event stream — new raw channel + normalize flag
+# ---------------------------------------------------------------------------
+
+
+def _evt(value: float) -> GameEvent:
+    return GameEvent(adapter_id="t", event_type="health", value=value)
+
+
+class TestGameEventNormalizeAndRaw:
+    def test_raw_value_none_before_first_event(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(event_type="health", event_bus=bus)
+        stream.start()
+        assert stream.get_raw_value() is None
+        stream.stop()
+
+    def test_raw_value_exposed_after_event(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(
+            event_type="health", min_game_value=0.0, max_game_value=100.0, event_bus=bus
+        )
+        stream.start()
+        bus.publish(_evt(73.0))
+        assert stream.get_value() == pytest.approx(0.73)  # normalized output
+        assert stream.get_raw_value() == pytest.approx(73.0)  # un-clamped raw
+        stream.stop()
+
+    def test_normalize_false_clamps_output_keeps_raw(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(
+            event_type="health",
+            min_game_value=0.0,
+            max_game_value=100.0,
+            normalize=False,
+            event_bus=bus,
+        )
+        stream.start()
+        bus.publish(_evt(50.0))  # 50 is > 1 -> clamped to 1.0 in passthrough mode
+        assert stream.get_value() == 1.0
+        assert stream.get_raw_value() == pytest.approx(50.0)
+        stream.stop()
+
+    def test_normalize_false_in_range_fraction(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(event_type="health", normalize=False, event_bus=bus)
+        stream.start()
+        bus.publish(_evt(0.4))
+        assert stream.get_value() == pytest.approx(0.4)
+        stream.stop()
+
+    def test_get_value_always_finite_in_passthrough(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(event_type="health", normalize=False, event_bus=bus)
+        stream.start()
+        bus.publish(_evt(math.inf))
+        assert stream.get_value() == 0.0  # finite-safe clamp
+        stream.stop()
+
+
+# ---------------------------------------------------------------------------
+# Live update_source() flip of the normalize flag on a running stream
+# ---------------------------------------------------------------------------
+
+# The design's load-bearing invariant: flipping normalize live never blends a
+# raw magnitude against a fraction in the EMA, because BOTH modes emit [0,1].
+# These tests lock that in (a future regression dropping a stream's
+# _normalize_enabled reassignment would otherwise pass every other test).
+
+
+class TestLiveNormalizeFlip:
+    def test_http_flip_true_to_false_and_back(self):
+        s = _http(True, 50.0)
+        assert s.get_value() == pytest.approx(0.5)  # rescaled
+        s.update_source(
+            ValueSource.from_dict(
+                _base(
+                    "http", http_endpoint_id="ep", min_value=0.0, max_value=100.0, normalize=False
+                )
+            )
+        )
+        assert s.get_value() == 1.0  # now clamp-passthrough of 50.0
+        s.update_source(
+            ValueSource.from_dict(
+                _base("http", http_endpoint_id="ep", min_value=0.0, max_value=100.0, normalize=True)
+            )
+        )
+        assert s.get_value() == pytest.approx(0.5)  # rescaled again, no stale-cache blend
+
+    def test_ha_flip_true_to_false(self):
+        s = _ha(True, "50")
+        assert s.get_value() == pytest.approx(0.5)
+        s.update_source(
+            ValueSource.from_dict(
+                _base(
+                    "ha_entity",
+                    ha_source_id="ha1",
+                    entity_id="sensor.temp",
+                    min_ha_value=0.0,
+                    max_ha_value=100.0,
+                    normalize=False,
+                )
+            )
+        )
+        assert s.get_value() == 1.0
+
+    def test_system_metrics_flip_true_to_false(self):
+        s = SystemMetricsValueStream(
+            metric="cpu_load", min_value=0.0, max_value=100.0, normalize=True
+        )
+        s._read_metric = lambda: 65.0  # type: ignore[method-assign]
+        first = s.get_value()  # rescaled via the cpu_load spec
+        assert 0.0 <= first <= 1.0
+        s.update_source(
+            ValueSource.from_dict(
+                _base(
+                    "system_metrics",
+                    metric="cpu_load",
+                    min_value=0.0,
+                    max_value=100.0,
+                    normalize=False,
+                )
+            )
+        )
+        s._read_metric = lambda: 65.0  # type: ignore[method-assign]
+        s._prev_value = None  # force a fresh poll (bypass the poll-interval cache)
+        assert s.get_value() == 1.0  # clamp-passthrough of 65.0
+
+    def test_game_event_flip_true_to_false(self):
+        bus = GameEventBus()
+        stream = GameEventValueStream(
+            event_type="health",
+            min_game_value=0.0,
+            max_game_value=100.0,
+            normalize=True,
+            event_bus=bus,
+        )
+        stream.start()
+        bus.publish(_evt(50.0))
+        assert stream.get_value() == pytest.approx(0.5)
+        stream.update_source(
+            ValueSource.from_dict(
+                _base("game_event", min_game_value=0.0, max_game_value=100.0, normalize=False)
+            )
+        )
+        bus.publish(_evt(50.0))
+        assert stream.get_value() == 1.0  # clamp-passthrough
+        assert stream.get_raw_value() == pytest.approx(50.0)
+        stream.stop()
+
+
+# ---------------------------------------------------------------------------
+# build_stream() forwarding — game_event's SOLE wiring path (no CRUD/schema)
+# ---------------------------------------------------------------------------
+
+
+class TestBuildStreamForwarding:
+    def test_game_event_builder_forwards_normalize(self):
+        src = ValueSource.from_dict(
+            _base("game_event", min_game_value=0.0, max_game_value=100.0, normalize=False)
+        )
+        bus = GameEventBus()
+        deps = ValueStreamDeps(value_stream_manager=None, event_bus=bus)
+        stream = build_stream(src, deps)
+        assert isinstance(stream, GameEventValueStream)
+        assert stream._normalize_enabled is False  # forwarded from the dataclass
+        stream.start()
+        bus.publish(_evt(50.0))
+        assert stream.get_value() == 1.0  # passthrough clamp, not 0.5 rescale
+        assert stream.get_raw_value() == pytest.approx(50.0)
+        stream.stop()

server/tests/core/test_android_audio_engine.py

@@ -0,0 +1,253 @@
+"""Tests for the Android playback-capture audio engine.
+
+These run on desktop CI (no Android device needed): ``is_android`` is
+monkeypatched and PCM is pushed directly into the module-level queue,
+exactly as the Kotlin bridge would.
+"""
+
+import queue
+
+import numpy as np
+import pytest
+
+# Importing the package triggers auto-registration of AndroidAudioEngine.
+import ledgrab.core.audio  # noqa: F401
+from ledgrab.core.audio import android_audio_engine as eng
+from ledgrab.core.audio.analysis import AudioAnalysis, AudioAnalyzer
+from ledgrab.core.audio.audio_capture import AudioCaptureManager
+from ledgrab.core.audio.factory import AudioEngineRegistry
+
+ENGINE_MOD = "ledgrab.core.audio.android_audio_engine"
+SAMPLE_RATE = 48000
+CHANNELS = 2
+CHUNK = 1024
+
+
+# ---------------------------------------------------------------------------
+# Helpers / fixtures
+# ---------------------------------------------------------------------------
+
+
+def _drain() -> None:
+    while not eng._pcm_queue.empty():
+        try:
+            eng._pcm_queue.get_nowait()
+        except queue.Empty:
+            break
+
+
+def _block(marker: float = 0.0, frames: int = CHUNK, channels: int = CHANNELS) -> np.ndarray:
+    """A float32 interleaved block whose first sample is ``marker``."""
+    data = np.zeros(frames * channels, dtype=np.float32)
+    data[0] = marker
+    return data
+
+
+@pytest.fixture
+def reset_engine():
+    """Reset module-global engine state; snapshot/restore the registry.
+
+    The engine keeps its queue + format in module globals and the registry
+    is a class-level singleton — both must be restored so this test file
+    never disturbs the desktop engines other tests rely on.
+    """
+    saved_engines = dict(AudioEngineRegistry._engines)
+    eng.shutdown()
+    _drain()
+    eng._sample_rate = SAMPLE_RATE
+    eng._channels = CHANNELS
+    eng._chunk_size = CHUNK
+    eng._frames_received = 0
+
+    yield eng
+
+    eng.shutdown()
+    _drain()
+    AudioEngineRegistry._engines.clear()
+    AudioEngineRegistry._engines.update(saved_engines)
+
+
+@pytest.fixture
+def on_android(monkeypatch, reset_engine):
+    """Engine fixture with ``is_android`` forced True and demo mode off."""
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    monkeypatch.setattr("ledgrab.core.audio.factory.is_demo_mode", lambda: False)
+    return reset_engine
+
+
+# ---------------------------------------------------------------------------
+# Queue / push contract
+# ---------------------------------------------------------------------------
+
+
+def test_configure_then_push_round_trips_samples(reset_engine):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    samples = np.arange(CHUNK * CHANNELS, dtype=np.float32)
+
+    # Act
+    eng.push_samples(samples.tobytes())
+    stream = eng.AndroidAudioEngine.create_stream(0, True, {})
+    stream.initialize()
+    got = stream.read_chunk()
+
+    # Assert
+    assert got is not None
+    np.testing.assert_array_equal(got, samples)
+
+
+def test_queue_drops_oldest_when_full(reset_engine):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    maxsize = eng._pcm_queue.maxsize  # 8
+
+    # Act — push more blocks than the queue can hold, each tagged 0..N-1
+    total = maxsize + 2
+    for i in range(total):
+        eng.push_samples(_block(marker=float(i)).tobytes())
+
+    drained = []
+    while True:
+        try:
+            drained.append(eng._pcm_queue.get_nowait())
+        except queue.Empty:
+            break
+
+    # Assert — only the newest `maxsize` blocks survived, oldest dropped
+    assert len(drained) == maxsize
+    markers = [int(b[0]) for b in drained]
+    assert markers == list(range(total - maxsize, total))
+
+
+def test_initialize_raises_when_not_configured(reset_engine):
+    # Arrange — fixture left the engine inactive
+    stream = eng.AndroidAudioEngine.create_stream(0, True, {})
+
+    # Act / Assert
+    with pytest.raises(RuntimeError):
+        stream.initialize()
+
+
+def test_read_chunk_returns_none_when_empty(reset_engine):
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    stream = eng.AndroidAudioEngine.create_stream(0, True, {})
+    stream.initialize()
+    assert stream.read_chunk() is None
+
+
+# ---------------------------------------------------------------------------
+# Availability / enumeration (platform-gated)
+# ---------------------------------------------------------------------------
+
+
+def test_is_available_requires_android_and_active(monkeypatch, reset_engine):
+    # Not configured yet → inactive → unavailable even on Android.
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    assert eng.AndroidAudioEngine.is_available() is False
+
+    # Configured → active + Android → available.
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    assert eng.AndroidAudioEngine.is_available() is True
+
+    # Active but not on Android → unavailable.
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: False)
+    assert eng.AndroidAudioEngine.is_available() is False
+
+
+def test_enumerate_devices(on_android):
+    # Inactive → no devices.
+    assert eng.AndroidAudioEngine.enumerate_devices() == []
+
+    # Active → exactly one loopback device.
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    devices = eng.AndroidAudioEngine.enumerate_devices()
+    assert len(devices) == 1
+    dev = devices[0]
+    assert dev.is_loopback is True
+    assert dev.is_input is True
+    assert "Android playback" in dev.name
+    assert dev.channels == CHANNELS
+
+
+# ---------------------------------------------------------------------------
+# Regression guard — the analyzer must never crash on a malformed block
+# (over-length or non-frame-divisible). This is the on-device failure the
+# plan review surfaced; the desktop suite must catch it.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "raw_floats",
+    [
+        (CHUNK + 100) * CHANNELS,  # over-length (more frames than chunk_size)
+        CHUNK * CHANNELS + 1,  # not a whole number of stereo frames
+        3,  # tiny + odd
+        CHUNK * CHANNELS,  # exact (control)
+    ],
+)
+def test_pushed_block_never_crashes_analyzer(reset_engine, raw_floats):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    pcm = np.random.default_rng(0).standard_normal(raw_floats).astype(np.float32)
+    analyzer = AudioAnalyzer(sample_rate=SAMPLE_RATE, chunk_size=CHUNK)
+    stream = eng.AndroidAudioEngine.create_stream(0, True, {})
+    stream.initialize()
+
+    # Act
+    eng.push_samples(pcm.tobytes())
+    chunk = stream.read_chunk()
+
+    # Assert — chunk is a safe shape and analyze() does not raise.
+    assert chunk is not None
+    assert len(chunk) % CHANNELS == 0
+    assert len(chunk) <= CHUNK * CHANNELS
+    analysis = analyzer.analyze(chunk, CHANNELS)
+    assert isinstance(analysis, AudioAnalysis)
+
+
+# ---------------------------------------------------------------------------
+# Registry integration
+# ---------------------------------------------------------------------------
+
+
+def test_best_available_engine_is_android_when_active(on_android):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+
+    # Act
+    best = AudioEngineRegistry.get_best_available_engine()
+
+    # Assert — priority 100 beats every desktop engine; demo only wins in demo mode.
+    assert best == "android_playback"
+
+
+def test_stream_via_registry_yields_pushed_chunk(on_android):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+    samples = np.linspace(-1.0, 1.0, CHUNK * CHANNELS, dtype=np.float32)
+
+    # Act
+    stream = AudioEngineRegistry.create_stream("android_playback", 0, True, {})
+    stream.initialize()
+    eng.push_samples(samples.tobytes())
+    got = stream.read_chunk()
+
+    # Assert
+    assert stream.channels == CHANNELS
+    assert stream.sample_rate == SAMPLE_RATE
+    assert stream.chunk_size == CHUNK
+    np.testing.assert_array_equal(got, samples)
+
+
+def test_device_surfaces_through_capture_manager(on_android):
+    # Arrange
+    eng.configure(SAMPLE_RATE, CHANNELS, CHUNK)
+
+    # Act
+    devices = AudioCaptureManager.enumerate_devices()
+
+    # Assert — the Android device is enumerated and tagged with its engine.
+    android = [d for d in devices if d["engine_type"] == "android_playback"]
+    assert len(android) == 1
+    assert android[0]["name"] == "Android playback (system audio)"
+    assert android[0]["is_loopback"] is True

server/tests/core/test_android_camera_engine.py

@@ -0,0 +1,342 @@
+"""Tests for the Android camera (webcam) capture engine.
+
+These run on desktop CI (no Android device needed): ``is_android`` and the
+Kotlin-bridge hooks (``list_cameras`` / ``start_camera`` / ``stop_camera``)
+are monkeypatched, and RGB frames are pushed directly into the module-level
+queue, exactly as the Kotlin ``CameraBridge`` would.
+"""
+
+import queue
+
+import numpy as np
+import pytest
+
+# Importing the package triggers auto-registration of AndroidCameraEngine.
+import ledgrab.core.capture_engines  # noqa: F401
+from ledgrab.core.capture_engines import android_camera_engine as eng
+from ledgrab.core.capture_engines.factory import EngineRegistry
+
+ENGINE_MOD = "ledgrab.core.capture_engines.android_camera_engine"
+W = 16
+H = 8
+
+_FAKE_CAMERAS = [
+    {"index": 0, "name": "Back camera", "facing": "back"},
+    {"index": 1, "name": "Front camera", "facing": "front"},
+]
+
+
+# ---------------------------------------------------------------------------
+# Helpers / fixtures
+# ---------------------------------------------------------------------------
+
+
+def _drain() -> None:
+    while not eng._frame_queue.empty():
+        try:
+            eng._frame_queue.get_nowait()
+        except queue.Empty:
+            break
+
+
+def _frame(marker: int = 0, w: int = W, h: int = H) -> bytes:
+    """A tightly-packed RGB frame whose first pixel's R channel is ``marker``."""
+    arr = np.zeros((h, w, 3), dtype=np.uint8)
+    arr[0, 0, 0] = marker
+    return arr.tobytes()
+
+
+@pytest.fixture
+def reset_engine():
+    """Reset module-global engine state; snapshot/restore the registry.
+
+    The engine keeps its queue + caches in module globals and the registry
+    is a class-level singleton — both must be restored so this test file
+    never disturbs the desktop engines other tests rely on.
+    """
+    saved_engines = dict(EngineRegistry._engines)
+    eng.shutdown()
+    _drain()
+    eng._frames_received = 0
+    eng._active = False
+    eng._active_index = 0
+    eng._last_frame = None
+    eng._cam_cache = None
+    eng._cam_cache_time = 0.0
+    eng._owner_index = None
+    eng._owner_refs = 0
+
+    yield eng
+
+    eng.shutdown()
+    _drain()
+    eng._cam_cache = None
+    eng._cam_cache_time = 0.0
+    eng._owner_index = None
+    eng._owner_refs = 0
+    EngineRegistry._engines.clear()
+    EngineRegistry._engines.update(saved_engines)
+
+
+@pytest.fixture
+def on_android(monkeypatch, reset_engine):
+    """Engine fixture with ``is_android`` True, demo mode off, fake cameras,
+    and the open/close hooks stubbed to succeed (recording calls)."""
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    monkeypatch.setattr("ledgrab.core.capture_engines.factory.is_demo_mode", lambda: False)
+    monkeypatch.setattr(f"{ENGINE_MOD}.list_cameras", lambda: list(_FAKE_CAMERAS))
+
+    calls = {"start": [], "stop": []}
+    monkeypatch.setattr(
+        f"{ENGINE_MOD}.start_camera",
+        lambda index, w, h: calls["start"].append((index, w, h)) or True,
+    )
+    monkeypatch.setattr(
+        f"{ENGINE_MOD}.stop_camera",
+        lambda index: calls["stop"].append(index),
+    )
+    reset_engine.calls = calls
+    return reset_engine
+
+
+# ---------------------------------------------------------------------------
+# Queue / push contract
+# ---------------------------------------------------------------------------
+
+
+def test_push_frame_round_trips_rgb(on_android):
+    # Arrange
+    stream = eng.AndroidCameraEngine.create_stream(0, {})
+    stream.initialize()
+
+    # Act
+    eng.push_frame(_frame(marker=42), W, H)
+    got = stream.capture_frame()
+
+    # Assert
+    assert got is not None
+    assert got.image.shape == (H, W, 3)
+    assert got.image.dtype == np.uint8
+    assert int(got.image[0, 0, 0]) == 42
+    assert got.width == W and got.height == H
+
+
+def test_queue_drops_oldest_when_full(reset_engine):
+    # Arrange
+    maxsize = eng._frame_queue.maxsize  # 2
+
+    # Act — push more frames than the queue holds, each tagged 0..N-1
+    total = maxsize + 3
+    for i in range(total):
+        eng.push_frame(_frame(marker=i), W, H)
+
+    drained = []
+    while True:
+        try:
+            drained.append(eng._frame_queue.get_nowait())
+        except queue.Empty:
+            break
+
+    # Assert — only the newest `maxsize` frames survived, oldest dropped
+    assert len(drained) == maxsize
+    markers = [int(f.image[0, 0, 0]) for f in drained]
+    assert markers == list(range(total - maxsize, total))
+
+
+def test_capture_frame_falls_back_to_last_frame_when_empty(on_android):
+    # Arrange
+    stream = eng.AndroidCameraEngine.create_stream(0, {})
+    stream.initialize()
+    eng.push_frame(_frame(marker=7), W, H)
+
+    # Act — first read drains the queue; second read finds it empty
+    first = stream.capture_frame()
+    second = stream.capture_frame()
+
+    # Assert — the static-frame fallback returns the cached last frame
+    assert first is not None
+    assert second is not None
+    assert int(second.image[0, 0, 0]) == 7
+
+
+def test_push_frame_short_buffer_does_not_crash(reset_engine):
+    # A buffer shorter than width*height*3 must be dropped, not reshape-crash.
+    eng.push_frame(b"\x01\x02\x03", W, H)  # far too short
+    assert eng._frame_queue.empty()
+    assert eng._last_frame is None
+
+
+# ---------------------------------------------------------------------------
+# On-demand open/close lifecycle
+# ---------------------------------------------------------------------------
+
+
+def test_initialize_opens_camera_with_parsed_resolution(on_android):
+    stream = eng.AndroidCameraEngine.create_stream(1, {"resolution": "1280x720"})
+    stream.initialize()
+    assert on_android.calls["start"] == [(1, 1280, 720)]
+
+
+def test_initialize_auto_resolution_requests_zero(on_android):
+    stream = eng.AndroidCameraEngine.create_stream(0, {"resolution": "auto"})
+    stream.initialize()
+    assert on_android.calls["start"] == [(0, 0, 0)]
+
+
+def test_cleanup_closes_camera_once(on_android):
+    stream = eng.AndroidCameraEngine.create_stream(0, {})
+    stream.initialize()
+    stream.cleanup()
+    assert on_android.calls["stop"] == [0]
+    # Idempotent — a second cleanup does not re-signal the bridge.
+    stream.cleanup()
+    assert on_android.calls["stop"] == [0]
+
+
+def test_second_camera_index_is_refused(on_android):
+    # First stream owns camera 0.
+    s0 = eng.AndroidCameraEngine.create_stream(0, {})
+    s0.initialize()
+    # A stream on a DIFFERENT camera must be refused (one camera at a time),
+    # not silently steal camera 0's stream.
+    s1 = eng.AndroidCameraEngine.create_stream(1, {})
+    with pytest.raises(RuntimeError):
+        s1.initialize()
+    # Only the first open reached the bridge.
+    assert on_android.calls["start"] == [(0, 0, 0)]
+
+
+def test_same_camera_attaches_and_refcounts(on_android):
+    # Two streams on the SAME camera share one physical open (ref-counted).
+    a = eng.AndroidCameraEngine.create_stream(0, {})
+    b = eng.AndroidCameraEngine.create_stream(0, {})
+    a.initialize()
+    b.initialize()
+    assert on_android.calls["start"] == [(0, 0, 0)]  # opened once
+
+    # First release must NOT stop the camera (the other stream is still live).
+    a.cleanup()
+    assert on_android.calls["stop"] == []
+    # Last release stops it exactly once.
+    b.cleanup()
+    assert on_android.calls["stop"] == [0]
+
+
+def test_camera_freed_after_release_allows_other_index(on_android):
+    # After fully releasing camera 0, a different camera can be opened.
+    s0 = eng.AndroidCameraEngine.create_stream(0, {})
+    s0.initialize()
+    s0.cleanup()
+    s1 = eng.AndroidCameraEngine.create_stream(1, {})
+    s1.initialize()  # must not raise
+    assert on_android.calls["start"] == [(0, 0, 0), (1, 0, 0)]
+
+
+def test_initialize_raises_when_open_fails(monkeypatch, reset_engine):
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    monkeypatch.setattr(f"{ENGINE_MOD}.start_camera", lambda index, w, h: False)
+    stream = eng.AndroidCameraEngine.create_stream(0, {})
+    with pytest.raises(RuntimeError):
+        stream.initialize()
+
+
+def test_initialize_raises_off_android(monkeypatch, reset_engine):
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: False)
+    stream = eng.AndroidCameraEngine.create_stream(0, {})
+    with pytest.raises(RuntimeError):
+        stream.initialize()
+
+
+# ---------------------------------------------------------------------------
+# Availability / enumeration (platform-gated)
+# ---------------------------------------------------------------------------
+
+
+def test_is_available_requires_android_and_cameras(monkeypatch, reset_engine):
+    # Off-Android → unavailable regardless of cameras.
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: False)
+    monkeypatch.setattr(f"{ENGINE_MOD}.list_cameras", lambda: list(_FAKE_CAMERAS))
+    assert eng.AndroidCameraEngine.is_available() is False
+
+    # On-Android but no cameras → unavailable.
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    monkeypatch.setattr(f"{ENGINE_MOD}.list_cameras", lambda: [])
+    eng._cam_cache = None  # bust the enumeration cache
+    assert eng.AndroidCameraEngine.is_available() is False
+
+    # On-Android with ≥1 camera → available.
+    monkeypatch.setattr(f"{ENGINE_MOD}.list_cameras", lambda: list(_FAKE_CAMERAS))
+    eng._cam_cache = None
+    assert eng.AndroidCameraEngine.is_available() is True
+
+
+def test_get_available_displays_maps_cameras(on_android):
+    displays = eng.AndroidCameraEngine.get_available_displays()
+    assert len(displays) == 2
+    assert displays[0].index == 0 and displays[0].name == "Back camera"
+    assert displays[0].is_primary is True
+    assert displays[1].index == 1 and displays[1].name == "Front camera"
+    assert displays[1].is_primary is False
+
+
+def test_config_choices_expose_resolution(reset_engine):
+    choices = eng.AndroidCameraEngine.get_config_choices()
+    assert "resolution" in choices
+    assert "auto" in choices["resolution"]
+    assert "1920x1080" in choices["resolution"]
+
+
+# ---------------------------------------------------------------------------
+# Registry integration
+# ---------------------------------------------------------------------------
+
+
+def test_engine_registers_with_expected_type_and_priority():
+    # Auto-registration ran on import; the engine is in the registry.
+    assert "android_camera" in EngineRegistry.get_all_engines()
+    assert eng.AndroidCameraEngine.ENGINE_PRIORITY == 0
+    assert eng.AndroidCameraEngine.HAS_OWN_DISPLAYS is True
+
+
+def test_does_not_beat_mediaprojection_by_priority(monkeypatch, reset_engine):
+    """Priority 0 must never let the camera win the best-engine race over
+    MediaProjection (100) on Android."""
+    from ledgrab.core.capture_engines import mediaprojection_engine as mp
+
+    monkeypatch.setattr(f"{ENGINE_MOD}.is_android", lambda: True)
+    monkeypatch.setattr(f"{ENGINE_MOD}.list_cameras", lambda: list(_FAKE_CAMERAS))
+    monkeypatch.setattr("ledgrab.core.capture_engines.factory.is_demo_mode", lambda: False)
+    eng._cam_cache = None
+
+    # Controlled registry: just the two engines whose priority race we assert.
+    EngineRegistry._engines.clear()
+    EngineRegistry.register(mp.MediaProjectionEngine)
+    EngineRegistry.register(eng.AndroidCameraEngine)
+
+    mp.configure(640, 480)  # make MediaProjection available
+    try:
+        best = EngineRegistry.get_best_available_engine()
+        assert best == "mediaprojection"
+        assert best != "android_camera"
+    finally:
+        mp.shutdown()
+        while not mp._frame_queue.empty():
+            try:
+                mp._frame_queue.get_nowait()
+            except queue.Empty:
+                break
+
+
+def test_stream_via_registry_yields_pushed_frame(on_android):
+    # Arrange — register cleanly (fixture restores afterward).
+    stream = EngineRegistry.create_stream("android_camera", 0, {})
+    stream.initialize()
+
+    # Act
+    eng.push_frame(_frame(marker=99), W, H)
+    got = stream.capture_frame()
+
+    # Assert
+    assert got is not None
+    assert int(got.image[0, 0, 0]) == 99
+    assert got.display_index == 0

server/tests/core/test_android_foreground.py

@@ -0,0 +1,194 @@
+"""Tests for Android foreground-app detection in PlatformDetector.
+
+These run on desktop CI (no Android device needed): ``is_android`` and the
+Kotlin-bridge wrappers (``has_usage_access`` / ``get_foreground_package``) are
+monkeypatched, exactly as the Kotlin ``ForegroundAppBridge`` would drive them on
+device. The critical invariant under test is that the Android branch runs *ahead
+of* the import-time ``_IS_WINDOWS`` guard, and that the Windows/desktop paths are
+left untouched.
+"""
+
+import pytest
+
+from ledgrab.core.automations import platform_detector as pd
+from ledgrab.core.automations.platform_detector import PlatformDetector
+
+
+@pytest.fixture
+def detector(monkeypatch):
+    """A PlatformDetector with the Windows display-power listener stubbed out.
+
+    ``__init__`` otherwise spawns a thread that registers a global window class +
+    runs a ctypes message pump — irrelevant here and noisy when many detectors are
+    constructed in one process.
+    """
+    monkeypatch.setattr(PlatformDetector, "_display_power_listener", lambda self: None)
+    return PlatformDetector()
+
+
+@pytest.fixture(autouse=True)
+def _reset_warn():
+    """Reset the process-global warn-once flag around every test."""
+    pd._warned_no_usage_access = False
+    yield
+    pd._warned_no_usage_access = False
+
+
+# ---------------------------------------------------------------------------
+# topmost (foreground) detection
+# ---------------------------------------------------------------------------
+
+
+def test_topmost_android_returns_lowercased_foreground_package(detector, monkeypatch):
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: True)
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: "com.Netflix.MediaClient")
+
+    assert detector._get_topmost_process_sync() == ("com.netflix.mediaclient", True)
+
+
+def test_topmost_android_no_access_returns_none_and_warns_once(detector, monkeypatch):
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: False)
+    fg_calls = []
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: fg_calls.append(1) or "x")
+    warns = []
+    monkeypatch.setattr(pd.logger, "warning", lambda *a, **k: warns.append(a))
+
+    assert detector._get_topmost_process_sync() == (None, False)
+    assert detector._get_topmost_process_sync() == (None, False)
+
+    # Foreground is never queried when access is missing; warned exactly once.
+    assert fg_calls == []
+    assert len(warns) == 1
+    assert pd._warned_no_usage_access is True
+
+
+def test_topmost_android_no_foreground_event_returns_none(detector, monkeypatch):
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: True)
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: None)
+
+    assert detector._get_topmost_process_sync() == (None, False)
+
+
+def test_android_branch_precedes_windows_guard(detector, monkeypatch):
+    """Even with _IS_WINDOWS True, is_android() must win.
+
+    Proves the Android branch sits ahead of the ``if not _IS_WINDOWS`` early
+    return and never falls through to the Win32 ctypes path (the plan-review
+    critical gap: a naive wiring would no-op behind the Windows guard).
+    """
+    monkeypatch.setattr(pd, "_IS_WINDOWS", True)
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: True)
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: "com.App.X")
+
+    assert detector._get_topmost_process_sync() == ("com.app.x", True)
+
+
+# ---------------------------------------------------------------------------
+# running / fullscreen best-effort (foreground app as the sole entry)
+# ---------------------------------------------------------------------------
+
+
+def test_running_and_fullscreen_android_return_foreground_set(detector, monkeypatch):
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: True)
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: "com.App.Y")
+
+    assert detector._get_running_processes_sync() == {"com.app.y"}
+    assert detector._get_fullscreen_processes_sync() == {"com.app.y"}
+
+
+def test_running_and_fullscreen_android_empty_without_access(detector, monkeypatch):
+    monkeypatch.setattr(pd, "is_android", lambda: True)
+    monkeypatch.setattr(pd, "has_usage_access", lambda: False)
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: "x")
+
+    assert detector._get_running_processes_sync() == set()
+    assert detector._get_fullscreen_processes_sync() == set()
+
+
+# ---------------------------------------------------------------------------
+# desktop paths untouched
+# ---------------------------------------------------------------------------
+
+
+def test_non_android_non_windows_skips_bridge(detector, monkeypatch):
+    """Desktop Linux/mac: no Android branch, no Win32 path, empty results, and
+    the bridge wrappers are never consulted."""
+    monkeypatch.setattr(pd, "_IS_WINDOWS", False)
+    monkeypatch.setattr(pd, "is_android", lambda: False)
+    calls = []
+    monkeypatch.setattr(pd, "get_foreground_package", lambda: calls.append("fg"))
+    monkeypatch.setattr(pd, "has_usage_access", lambda: calls.append("acc") or True)
+
+    assert detector._get_topmost_process_sync() == (None, False)
+    assert detector._get_running_processes_sync() == set()
+    assert detector._get_fullscreen_processes_sync() == set()
+    assert calls == []
+
+
+def test_wrappers_return_safe_defaults_off_android(monkeypatch):
+    """is_android() False short-circuits the bridge accessor to None, so the
+    public wrappers return safe defaults without any java interop."""
+    monkeypatch.setattr(pd, "is_android", lambda: False)
+
+    assert pd._foreground_bridge() is None
+    assert pd.has_usage_access() is False
+    assert pd.get_foreground_package() is None
+    assert pd.list_installed_apps() == []
+
+
+# ---------------------------------------------------------------------------
+# bridge-response parsing wrappers (fed via a fake bridge object)
+# ---------------------------------------------------------------------------
+
+
+class _FakeBridge:
+    """Stand-in for the Kotlin ForegroundAppBridge singleton."""
+
+    def __init__(self, fg=None, apps_json=None):
+        self._fg = fg
+        self._apps_json = apps_json
+
+    def getForegroundPackage(self):
+        return self._fg
+
+    def listLaunchableApps(self):
+        return self._apps_json
+
+
+def test_get_foreground_package_strips_whitespace(monkeypatch):
+    # Stripped but NOT lowercased — the caller (_get_android_foreground) lowercases.
+    monkeypatch.setattr(pd, "_foreground_bridge", lambda: _FakeBridge(fg="  com.App.X  "))
+    assert pd.get_foreground_package() == "com.App.X"
+
+
+def test_get_foreground_package_blank_returns_none(monkeypatch):
+    monkeypatch.setattr(pd, "_foreground_bridge", lambda: _FakeBridge(fg="   "))
+    assert pd.get_foreground_package() is None
+
+
+def test_list_installed_apps_parses_and_filters(monkeypatch):
+    import json
+
+    payload = json.dumps(
+        [
+            {"package": "com.a", "label": "A"},
+            {"package": "com.b", "label": ""},  # blank label -> falls back to package
+            {"label": "no package"},  # skipped: no package
+            "not a dict",  # skipped: not an object
+        ]
+    )
+    monkeypatch.setattr(pd, "_foreground_bridge", lambda: _FakeBridge(apps_json=payload))
+    assert pd.list_installed_apps() == [
+        {"package": "com.a", "label": "A"},
+        {"package": "com.b", "label": "com.b"},
+    ]
+
+
+def test_list_installed_apps_invalid_json_returns_empty(monkeypatch):
+    monkeypatch.setattr(pd, "_foreground_bridge", lambda: _FakeBridge(apps_json="not json{"))
+    assert pd.list_installed_apps() == []

server/tests/core/test_demo_seed.py

@@ -0,0 +1,50 @@
+"""Demo-seed regression tests (value sources, incl. the template combinator)."""
+
+from ledgrab.core.demo_seed import seed_demo_data
+from ledgrab.storage.database import Database
+from ledgrab.storage.value_source import StaticValueSource, TemplateValueSource
+from ledgrab.storage.value_source_store import ValueSourceStore
+
+
+def _seed(tmp_path):
+    db = Database(tmp_path / "demo.db")
+    seed_demo_data(db)
+    return db
+
+
+def test_demo_seeds_template_value_source(tmp_path):
+    db = _seed(tmp_path)
+    try:
+        store = ValueSourceStore(db)
+        by_id = {s.id: s for s in store.get_all_sources()}
+
+        base = by_id["vs_demo0001"]
+        boost = by_id["vs_demo0002"]
+        assert isinstance(base, StaticValueSource)
+        assert isinstance(boost, TemplateValueSource)
+        assert boost.template == "clamp(level * 1.5)"
+        assert boost.inputs == [{"name": "level", "value_source_id": "vs_demo0001"}]
+
+        # The reference graph is intact and consistent.
+        assert store.get_transitive_dependencies("vs_demo0002") == {"vs_demo0001"}
+        assert store.find_referencing_sources("vs_demo0001") == [boost.name]
+    finally:
+        db.close()
+
+
+def test_demo_template_evaluates_through_manager(tmp_path):
+    """The seeded template must actually evaluate over its seeded input."""
+    from ledgrab.core.processing.value_stream import ValueStreamManager
+
+    db = _seed(tmp_path)
+    try:
+        store = ValueSourceStore(db)
+        vsm = ValueStreamManager(value_source_store=store)
+        stream = vsm.acquire("vs_demo0002")
+        try:
+            # base level 0.5 -> clamp(0.5 * 1.5) = 0.75
+            assert abs(stream.get_value() - 0.75) < 1e-6
+        finally:
+            vsm.release("vs_demo0002")
+    finally:
+        db.close()

server/tests/storage/test_template_value_source.py

@@ -0,0 +1,231 @@
+"""Tests for the template value source: model, factory, cycle/depth, refs."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from ledgrab.storage.value_source import TemplateValueSource
+
+
+class TestModelRoundTrip:
+    def _make(self, **over):
+        now = datetime.now(timezone.utc)
+        defaults = dict(
+            id="vs_t1",
+            name="Combo",
+            source_type="template",
+            created_at=now,
+            updated_at=now,
+            template="min(a * 2, 1)",
+            inputs=[{"name": "a", "value_source_id": "vs_a"}],
+            default_value=0.2,
+            eval_interval=1.5,
+        )
+        defaults.update(over)
+        return TemplateValueSource(**defaults)
+
+    def test_to_from_dict_idempotent(self):
+        src = self._make()
+        rebuilt = TemplateValueSource.from_dict(src.to_dict())
+        assert rebuilt.template == src.template
+        assert rebuilt.inputs == src.inputs
+        assert rebuilt.default_value == src.default_value
+        assert rebuilt.eval_interval == src.eval_interval
+        assert rebuilt.to_dict()["return_type"] == "float"
+
+    def test_old_row_deserializes_with_defaults(self):
+        """A row written before template fields existed must load safely."""
+        now = datetime.now(timezone.utc).isoformat()
+        src = TemplateValueSource.from_dict(
+            {
+                "id": "vs_old",
+                "name": "Old",
+                "source_type": "template",
+                "created_at": now,
+                "updated_at": now,
+            }
+        )
+        assert src.template == ""
+        assert src.inputs == []
+        assert src.default_value == 0.0
+        assert src.eval_interval is None
+
+    def test_dirty_scalars_coerce_to_defaults(self):
+        """Non-numeric stored scalars must not drop the whole row on load."""
+        src = TemplateValueSource.from_dict(
+            {
+                "id": "x",
+                "name": "n",
+                "source_type": "template",
+                "template": "a",
+                "default_value": "not-a-number",
+                "eval_interval": "bad",
+            }
+        )
+        assert src.default_value == 0.0
+        assert src.eval_interval is None
+
+    def test_inputs_normalized_from_dirty_data(self):
+        src = TemplateValueSource.from_dict(
+            {
+                "id": "x",
+                "name": "n",
+                "source_type": "template",
+                "inputs": [{"name": "a", "value_source_id": "vs_a"}, "junk", {"bad": 1}],
+            }
+        )
+        # non-dict entries dropped; dict entries coerced to {name, value_source_id}
+        assert src.inputs == [
+            {"name": "a", "value_source_id": "vs_a"},
+            {"name": "", "value_source_id": ""},
+        ]
+
+
+class TestFactoryCreate:
+    def test_create_valid(self, value_source_store):
+        src = value_source_store.create_source(
+            "Combo",
+            "template",
+            template="min(a * 2, 1)",
+            inputs=[{"name": "a", "value_source_id": ""}],
+            default_value=0.3,
+        )
+        assert isinstance(src, TemplateValueSource)
+        assert src.id.startswith("vs_")
+        assert src.default_value == 0.3
+
+    def test_empty_template_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source("X", "template", template="   ", inputs=[])
+
+    def test_compile_error_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source("X", "template", template="a +", inputs=[])
+
+    def test_cost_bomb_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source("X", "template", template="10 ** 10", inputs=[])
+
+    def test_reserved_input_name_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source(
+                "X",
+                "template",
+                template="min(0, 1)",
+                inputs=[{"name": "min", "value_source_id": "vs_a"}],
+            )
+
+    def test_duplicate_input_name_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source(
+                "X",
+                "template",
+                template="a",
+                inputs=[
+                    {"name": "a", "value_source_id": "vs_a"},
+                    {"name": "a", "value_source_id": "vs_b"},
+                ],
+            )
+
+    def test_default_value_out_of_range_rejected(self, value_source_store):
+        with pytest.raises(ValueError):
+            value_source_store.create_source(
+                "X",
+                "template",
+                template="a",
+                inputs=[{"name": "a", "value_source_id": ""}],
+                default_value=5.0,
+            )
+
+    def test_unbound_variable_rejected(self, value_source_store):
+        # 'ha_enti' is referenced but only 'ha_entity' is bound (typo) → reject.
+        with pytest.raises(ValueError):
+            value_source_store.create_source(
+                "X",
+                "template",
+                template="ha_enti",
+                inputs=[{"name": "ha_entity", "value_source_id": ""}],
+            )
+
+
+class TestFactoryUpdate:
+    def test_partial_update_template_only(self, value_source_store):
+        src = value_source_store.create_source(
+            "X",
+            "template",
+            template="a",
+            inputs=[{"name": "a", "value_source_id": ""}],
+            default_value=0.1,
+        )
+        updated = value_source_store.update_source(src.id, template="clamp(a * 3)")
+        assert updated.template == "clamp(a * 3)"
+        assert updated.default_value == 0.1  # unchanged
+
+    def test_update_invalid_template_rejected(self, value_source_store):
+        src = value_source_store.create_source("X", "template", template="clamp(0.5)", inputs=[])
+        with pytest.raises(ValueError):
+            value_source_store.update_source(src.id, template="a |")
+
+
+class TestCycleAndDepth:
+    def test_self_reference_rejected(self, value_source_store):
+        t = value_source_store.create_source("T", "template", template="clamp(0.5)", inputs=[])
+        with pytest.raises(ValueError):
+            value_source_store.update_source(t.id, inputs=[{"name": "x", "value_source_id": t.id}])
+
+    def test_circular_reference_rejected(self, value_source_store):
+        t1 = value_source_store.create_source("T1", "template", template="clamp(0.5)", inputs=[])
+        t2 = value_source_store.create_source(
+            "T2",
+            "template",
+            template="x",
+            inputs=[{"name": "x", "value_source_id": t1.id}],
+        )
+        # t1 -> t2 -> t1 would be a cycle
+        with pytest.raises(ValueError):
+            value_source_store.update_source(
+                t1.id, inputs=[{"name": "x", "value_source_id": t2.id}]
+            )
+
+    def test_deep_chain_rejected(self, value_source_store):
+        prev = value_source_store.create_source("L0", "template", template="clamp(0.5)", inputs=[])
+        created = 1
+        with pytest.raises(ValueError):
+            for i in range(1, 12):
+                node = value_source_store.create_source(
+                    f"L{i}",
+                    "template",
+                    template="x",
+                    inputs=[{"name": "x", "value_source_id": prev.id}],
+                )
+                prev = node
+                created += 1
+        # Should have rejected before building an unbounded chain.
+        assert created <= 8
+
+    def test_get_transitive_dependencies(self, value_source_store):
+        leaf = value_source_store.create_source(
+            "leaf", "template", template="clamp(0.5)", inputs=[]
+        )
+        mid = value_source_store.create_source(
+            "mid", "template", template="x", inputs=[{"name": "x", "value_source_id": leaf.id}]
+        )
+        top = value_source_store.create_source(
+            "top", "template", template="x", inputs=[{"name": "x", "value_source_id": mid.id}]
+        )
+        deps = value_source_store.get_transitive_dependencies(top.id)
+        assert deps == {mid.id, leaf.id}
+
+
+class TestReferencingSources:
+    def test_find_referencing_sources(self, value_source_store):
+        base = value_source_store.create_source("Base", "static", value=0.5)
+        tmpl = value_source_store.create_source(
+            "Uses",
+            "template",
+            template="b",
+            inputs=[{"name": "b", "value_source_id": base.id}],
+        )
+        refs = value_source_store.find_referencing_sources(base.id)
+        assert tmpl.name in refs
+        assert value_source_store.find_referencing_sources(tmpl.id) == []

server/tests/storage/test_value_source_store.py

@@ -7,7 +7,10 @@ from ledgrab.storage.value_source import (
     AnimatedValueSource,
     AudioValueSource,
     DaylightValueSource,
+    HAEntityValueSource,
+    HTTPValueSource,
     StaticValueSource,
+    SystemMetricsValueSource,
     ValueSource,
 )
 from ledgrab.storage.value_source_store import ValueSourceStore
@@ -238,6 +241,50 @@ class TestValueSourceStoreCRUD:
         assert updated.speed == 30.0
 
 
+# ---------------------------------------------------------------------------
+# normalize flag — full store create/update path (factory builder + applier)
+# ---------------------------------------------------------------------------
+
+
+class TestValueSourceNormalizeStoreRoundTrip:
+    """The ``normalize`` flag must survive the real write path —
+    create_source -> CREATE_BUILDERS and update_source -> UPDATE_APPLIERS —
+    not just dataclass from_dict/to_dict. A dropped builder/applier line would
+    silently revert/ignore the flag while every dataclass-level test stayed
+    green, so these exercise the factory layer end-to-end (game_event is
+    intentionally excluded — it has no store/CRUD path).
+    """
+
+    _CASES = [
+        ("ha_entity", {"ha_source_id": "ha1", "entity_id": "sensor.temp"}, HAEntityValueSource),
+        ("http", {"http_endpoint_id": "ep1"}, HTTPValueSource),
+        ("system_metrics", {"metric": "cpu_load"}, SystemMetricsValueSource),
+    ]
+
+    @pytest.mark.parametrize("source_type,kwargs,cls", _CASES)
+    def test_create_normalize_false_persists(self, store, source_type, kwargs, cls):
+        s = store.create_source(
+            name=f"{source_type}_n", source_type=source_type, normalize=False, **kwargs
+        )
+        assert isinstance(s, cls)
+        assert s.normalize is False
+        # Re-read exercises the SQLite blob persistence round-trip as well.
+        assert store.get_source(s.id).normalize is False
+
+    @pytest.mark.parametrize("source_type,kwargs,cls", _CASES)
+    def test_create_normalize_defaults_true(self, store, source_type, kwargs, cls):
+        s = store.create_source(name=f"{source_type}_d", source_type=source_type, **kwargs)
+        assert s.normalize is True
+
+    @pytest.mark.parametrize("source_type,kwargs,cls", _CASES)
+    def test_update_normalize_flip(self, store, source_type, kwargs, cls):
+        s = store.create_source(
+            name=f"{source_type}_u", source_type=source_type, normalize=False, **kwargs
+        )
+        assert store.update_source(s.id, normalize=True).normalize is True
+        assert store.update_source(s.id, normalize=False).normalize is False
+
+
 # ---------------------------------------------------------------------------
 # Name uniqueness
 # ---------------------------------------------------------------------------

server/tests/test_power_limit.py

@@ -0,0 +1,70 @@
+"""Unit tests for automatic brightness limiting (ABL) current estimation."""
+
+import numpy as np
+import pytest
+
+from ledgrab.core.processing.power_limit import (
+    DEFAULT_MILLIAMPS_PER_LED,
+    estimate_current_ma,
+    power_limit_scale,
+)
+
+
+def test_default_ma_per_led_constant():
+    assert DEFAULT_MILLIAMPS_PER_LED == 55
+
+
+def test_full_white_draws_ma_per_led_times_count():
+    colors = np.full((100, 3), 255, dtype=np.uint8)
+    assert estimate_current_ma(colors, 55) == pytest.approx(100 * 55)
+
+
+def test_black_draws_zero():
+    colors = np.zeros((100, 3), dtype=np.uint8)
+    assert estimate_current_ma(colors, 55) == 0.0
+
+
+def test_half_white_is_half_current():
+    full = estimate_current_ma(np.full((100, 3), 255, dtype=np.uint8), 55)
+    half = estimate_current_ma(np.full((100, 3), 128, dtype=np.uint8), 55)
+    assert half == pytest.approx(full * 128 / 255, rel=1e-6)
+
+
+def test_zero_ma_per_led_draws_zero():
+    colors = np.full((100, 3), 255, dtype=np.uint8)
+    assert estimate_current_ma(colors, 0) == 0.0
+
+
+def test_empty_frame_is_safe():
+    colors = np.zeros((0, 3), dtype=np.uint8)
+    assert estimate_current_ma(colors, 55) == 0.0
+    assert power_limit_scale(colors, 1000, 55) == 1.0
+
+
+def test_scale_is_one_when_disabled():
+    colors = np.full((100, 3), 255, dtype=np.uint8)
+    assert power_limit_scale(colors, 0, 55) == 1.0
+    assert power_limit_scale(colors, -1, 55) == 1.0
+
+
+def test_scale_is_one_within_budget():
+    colors = np.full((100, 3), 255, dtype=np.uint8)  # 5500 mA at 55 mA/LED
+    assert power_limit_scale(colors, 6000, 55) == 1.0
+    assert power_limit_scale(colors, 5500, 55) == 1.0  # exactly on budget
+
+
+def test_scale_brings_full_white_to_budget():
+    colors = np.full((100, 3), 255, dtype=np.uint8)  # 5500 mA
+    scale = power_limit_scale(colors, 2750, 55)  # half budget
+    assert scale == pytest.approx(0.5, rel=1e-6)
+
+
+def test_applying_scale_lands_within_budget():
+    colors = np.full((100, 3), 255, dtype=np.uint8)  # 5500 mA
+    budget = 2750
+    scale = power_limit_scale(colors, budget, 55)
+    # Mirror the processor's fixed-point application (factor/256).
+    factor = int(scale * 256)
+    scaled = ((colors.astype(np.uint16) * factor) >> 8).astype(np.uint8)
+    # Fixed-point rounding can only ever round DOWN, so we never exceed budget.
+    assert estimate_current_ma(scaled, 55) <= budget

server/tests/utils/test_template_expr.py

@@ -0,0 +1,136 @@
+"""Tests for the hardened sandboxed-Jinja expression engine."""
+
+import pytest
+
+from ledgrab.utils.template_expr import (
+    GLOBALS,
+    RESERVED_NAMES,
+    TemplateValidationError,
+    clamp,
+    compile_template,
+    extract_variables,
+    finalize_result,
+    validate_input_name,
+    validate_template_expression,
+)
+
+
+class TestCompileAndEval:
+    def test_basic_eval(self):
+        assert compile_template("min(a * 2, 1)")(a=0.3, raw={}) == pytest.approx(0.6)
+
+    def test_clamp_global(self):
+        assert compile_template("clamp((t - 18) / 10)")(t=22.5, raw={}) == pytest.approx(0.45)
+
+    def test_raw_subscript(self):
+        assert compile_template("raw['t'] / 100")(raw={"t": 42.0}) == pytest.approx(0.42)
+
+    def test_ternary_and_comparison(self):
+        expr = compile_template("a if a > 0.5 else b")
+        assert expr(a=0.8, b=0.1, raw={}) == pytest.approx(0.8)
+        assert expr(a=0.2, b=0.1, raw={}) == pytest.approx(0.1)
+
+    def test_all_globals_callable(self):
+        for tpl in ("min(a, b)", "max(a, b)", "abs(a - b)", "round(a, 1)", "clamp(a)"):
+            compile_template(tpl)(a=0.4, b=0.6, raw={})
+
+
+class TestRejections:
+    @pytest.mark.parametrize(
+        "tpl",
+        [
+            "",
+            "   ",
+            "a +",  # syntax error
+            "10 ** 3",  # power bomb
+            "'a' * 1000",  # string repetition
+            "a | pprint",  # filter
+            "a is defined",  # test
+            "a.__class__",  # attribute access
+            "raw['s'].format(1)",  # str gadget via attribute
+            "dict(x=1)",  # non-global call
+            "namespace(x=1)",
+            "range(3)",
+            "cycler(1, 2)",
+            "[0] * 1000000",  # list-literal repetition (memory bomb)
+            "(1,) * 1000000",  # tuple-literal repetition (memory bomb)
+            "[1, 2, 3]",  # bare list literal
+            "{1: 2}",  # dict literal
+        ],
+    )
+    def test_rejected(self, tpl):
+        with pytest.raises(TemplateValidationError):
+            validate_template_expression(tpl)
+
+    @pytest.mark.parametrize(
+        "tpl",
+        [
+            "min(a * 2, 1)",
+            "(a + b) / 2",
+            "clamp((t - 18) / 10, 0, 1)",
+            "raw['x'] / 100",
+            "a if a > b else b",
+            "abs(a - b)",
+        ],
+    )
+    def test_accepted(self, tpl):
+        validate_template_expression(tpl)  # must not raise
+
+
+class TestFinalizeResult:
+    def test_nan_returns_default(self):
+        assert finalize_result(float("nan"), 0.25) == 0.25
+
+    def test_inf_returns_default(self):
+        assert finalize_result(float("inf"), 0.25) == 0.25
+        assert finalize_result(float("-inf"), 0.25) == 0.25
+
+    def test_non_numeric_returns_default(self):
+        assert finalize_result("nope", 0.25) == 0.25
+        assert finalize_result(None, 0.25) == 0.25
+
+    def test_overflow_returns_default(self):
+        # float() of a multi-hundred-digit int (chained big-int multiply) raises
+        # OverflowError, not ValueError — must still fall back, not propagate.
+        assert finalize_result(10**400, 0.25) == 0.25
+
+    def test_clamps_to_unit(self):
+        assert finalize_result(5.0, 0.0) == 1.0
+        assert finalize_result(-1.0, 0.0) == 0.0
+        assert finalize_result(0.5, 0.0) == pytest.approx(0.5)
+
+    def test_clamp_helper(self):
+        assert clamp(2.0) == 1.0
+        assert clamp(-2.0) == 0.0
+        assert clamp(5.0, 0.0, 10.0) == 5.0
+
+
+class TestInputNames:
+    @pytest.mark.parametrize("name", ["audio", "cpu_load", "_x", "Temp2"])
+    def test_valid(self, name):
+        validate_input_name(name)
+
+    @pytest.mark.parametrize("name", ["", "1bad", "has space", "a-b", "a.b"])
+    def test_invalid_identifier(self, name):
+        with pytest.raises(TemplateValidationError):
+            validate_input_name(name)
+
+    @pytest.mark.parametrize("name", sorted(RESERVED_NAMES))
+    def test_reserved(self, name):
+        with pytest.raises(TemplateValidationError):
+            validate_input_name(name)
+
+    def test_globals_are_reserved(self):
+        assert set(GLOBALS).issubset(RESERVED_NAMES)
+        assert "raw" in RESERVED_NAMES
+
+
+class TestExtractVariables:
+    def test_excludes_globals_and_raw(self):
+        assert extract_variables("min(a, raw['x']) + b") == ["a", "b"]
+
+    def test_empty_for_uncompilable(self):
+        assert extract_variables("a +") == []
+
+    def test_constant_expression(self):
+        assert extract_variables("clamp(0.5)") == []