feat(value-sources): add sandboxed-Jinja template combinator

A new `template` value source evaluates a hardened, sandboxed Jinja
expression over the live values of other value sources — the system's
first float combinator.

Backend:
- Shared engine (utils/template_expr.py): ImmutableSandboxedEnvironment with
  filters/tests and auto-injected globals stripped; only min/max/abs/round/
  clamp exposed; rejects **, string/collection-literal repetition, attribute
  access and non-global calls; NaN/inf-safe result coercion.
- TemplateValueSource model + TemplateValueStream runtime: compile-once,
  primitives-only eval context, raw[name] exposure, eval_interval throttle,
  ref-counted input acquire/release, rename-safe hot-update.
- Validation: unbound-variable + reserved-name rejection, reference
  cycle/depth guards (depth-only at create, full cycle at update), runtime
  acquire() depth backstop, and delete referential-integrity.
- API: Create/Update/Response schemas + discriminated unions, _RESPONSE_MAP,
  and an advisory POST /value-sources/validate-template endpoint.
- Demo seed: a static source plus a template combinator example.

Frontend:
- Editor modal section: repeatable inputs list (EntitySelect rows), a
  zero-dependency Jinja syntax highlighter, a hints/reference panel, and a
  debounced live validator that gates Save (stale-response-safe).
- Graph editor: read-only template node with one edge per input.
- i18n (en/ru/zh), icon, and card rendering.

Tests: engine, stream, factory/cycle, validate endpoint, and demo seed.

docs/API.md

@@ -461,17 +461,22 @@ Reusable audio filter chains.
 
 ## Value sources
 
-Dynamic data inputs (brightness and other parameters): static, animated, audio, adaptive, color, sensor, HTTP, and Home Assistant.
+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 (`409` if referenced). |
+| 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.

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
@@ -231,6 +235,22 @@ _RESPONSE_MAP = {
         max_value=s.max_value,
         smoothing=s.smoothing,
     ),
+    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 +415,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 +431,100 @@ 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
+
+
 # ===== REAL-TIME VALUE SOURCE TEST WEBSOCKET =====
 
 

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."""
 
@@ -162,6 +173,19 @@ class HTTPValueSourceResponse(_ValueSourceResponseBase):
     smoothing: float = Field(description="EMA smoothing factor (0.0-1.0)")
 
 
+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[
     Annotated[StaticValueSourceResponse, Tag("static")]
     | Annotated[AnimatedValueSourceResponse, Tag("animated")]
@@ -176,7 +200,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"),
 ]
 
@@ -330,6 +355,27 @@ class HTTPValueSourceCreate(_ValueSourceCreateBase):
     smoothing: float = Field(0.0, description="EMA smoothing (0.0-1.0)", ge=0.0, le=1.0)
 
 
+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[
     Annotated[StaticValueSourceCreate, Tag("static")]
     | Annotated[AnimatedValueSourceCreate, Tag("animated")]
@@ -344,7 +390,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"),
 ]
 
@@ -490,6 +537,20 @@ class HTTPValueSourceUpdate(_ValueSourceUpdateBase):
     smoothing: float | None = Field(None, description="EMA smoothing", ge=0.0, le=1.0)
 
 
+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[
     Annotated[StaticValueSourceUpdate, Tag("static")]
     | Annotated[AnimatedValueSourceUpdate, Tag("animated")]
@@ -504,7 +565,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/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/value_kinds.py

@@ -267,6 +267,20 @@ def _build_http(source, d: ValueStreamDeps):
     )
 
 
+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 +304,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

@@ -34,6 +34,11 @@ 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.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
@@ -1365,6 +1376,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
 # ---------------------------------------------------------------------------
@@ -1644,6 +1817,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 +1836,29 @@ class ValueStreamManager:
             logger.info(f"Shared value stream {vs_id} (refs={self._ref_counts[vs_id]})")
             return self._streams[vs_id]
 
+        if self._acquire_depth >= _MAX_ACQUIRE_DEPTH:
+            logger.warning(
+                "Value source acquire depth limit (%d) reached at %s; returning "
+                "static fallback (possible reference cycle)",
+                _MAX_ACQUIRE_DEPTH,
+                vs_id,
+            )
+            # The intermediate referencing streams built while descending a
+            # cyclic chain are not stop()'d here — but this only triggers on a
+            # stored cycle that storage validation already rejects (e.g. a
+            # hand-edited DB / corrupt restore), so those transient objects are
+            # simply garbage-collected. Normal graphs never reach this depth.
+            return StaticValueStream(0.5)
+
         source = self._value_source_store.get_source(vs_id)
-        stream = self._create_stream(source, vs_id)
+        # Increment around create+start: a referencing stream (template /
-        stream.start()
+        # gradient_map) re-enters acquire() from its own start().
+        self._acquire_depth += 1
+        try:
+            stream = self._create_stream(source, vs_id)
+            stream.start()
+        finally:
+            self._acquire_depth -= 1
         self._streams[vs_id] = stream
         self._ref_counts[vs_id] = 1
         logger.info(f"Acquired value stream {vs_id} (type={source.source_type})")

server/src/ledgrab/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

@@ -187,6 +187,7 @@ import {
     addSchedulePoint,
     addAnimatedColor, removeAnimatedColor,
     addColorSchedulePoint, removeColorSchedulePoint,
+    addTemplateInput,
     testValueSource, closeTestValueSourceModal,
 } from './features/value-sources.ts';
 
@@ -584,6 +585,7 @@ Object.assign(window, {
     removeAnimatedColor,
     addColorSchedulePoint,
     removeColorSchedulePoint,
+    addTemplateInput,
     testValueSource,
     closeTestValueSourceModal,
 

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

@@ -176,6 +176,11 @@ 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 },

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

@@ -357,6 +357,16 @@ function buildGraph(e: EntitiesInput): { nodes: LayoutNode[]; edges: LayoutEdge[
         // 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

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 },

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/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];
 
@@ -633,6 +655,15 @@ 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);
+        } 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 = '';
@@ -707,6 +738,21 @@ 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);
+        // 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 +809,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';
 
@@ -962,6 +1021,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 +1452,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 +1583,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 +2060,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

@@ -336,6 +336,7 @@ startTargetOverlay: (...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;
 

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/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;
@@ -175,6 +180,15 @@ export interface HTTPValueSource extends ValueSourceBase {
     smoothing: number;
 }
 
+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 =
     | StaticValueSource
     | AnimatedValueSource
@@ -190,7 +204,8 @@ export type ValueSource =
     | CSSExtractValueSource
     | SystemMetricsValueSource
     | GameEventValueSource
-    | HTTPValueSource;
+    | HTTPValueSource
+    | TemplateValueSource;
 
 export interface ValueSourceListResponse {
     sources: ValueSource[];

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

@@ -3073,6 +3073,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

@@ -2755,6 +2755,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

@@ -2749,6 +2749,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/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
@@ -643,6 +648,69 @@ class HTTPValueSource(ValueSource):
         )
 
 
+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),
+        )
+
+
 # -- Source type registry --
 # Maps source_type string to its subclass for factory dispatch.
 _VALUE_SOURCE_MAP: Dict[str, Type[ValueSource]] = {
@@ -661,4 +729,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,
 )
@@ -365,6 +366,79 @@ def _build_http(
     )
 
 
+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,
+    )
+
+
 CREATE_BUILDERS: Dict[str, CreateBuilder] = {
     "static": _build_static,
     "animated": _build_animated,
@@ -381,6 +455,7 @@ CREATE_BUILDERS: Dict[str, CreateBuilder] = {
     "system_metrics": _build_system_metrics,
     "game_event": _build_game_event,
     "http": _build_http,
+    "template": _build_template,
 }
 
 
@@ -685,6 +760,45 @@ def _apply_http(
         source.smoothing = smoothing
 
 
+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] = {
     "static": _apply_static,
     "animated": _apply_animated,
@@ -701,6 +815,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,6 +25,11 @@ 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."""
@@ -67,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.
@@ -88,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)
@@ -119,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/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>
 
@@ -456,6 +457,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">

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_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/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/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/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)") == []