# New Value Source Types + Filter Support

## Feature 1: HA Value Source (`ha_entity`)

A value source that reads numeric values from a Home Assistant entity's state or attribute. Allows binding any scalar property in the system to a live HA sensor/entity value.

### Configuration
- `ha_source_id: str` — HA connection entity (EntitySelect picker)
- `entity_id: str` — HA entity (EntitySelect picker, populated from `/api/v1/home-assistant/sources/{id}/entities`)
- `attribute: str` — optional attribute name (text input or dropdown populated from entity attributes)
- `min_ha_value: float` — raw HA value corresponding to output 0.0
- `max_ha_value: float` — raw HA value corresponding to output 1.0
- `smoothing: float` — EMA smoothing factor (0..1)
- `return_type: "float"` — always float

### Backend

- [ ] **Storage model** — `HAEntityValueSource` subclass in `storage/value_source.py`
  - Fields: `ha_source_id`, `entity_id`, `attribute`, `min_ha_value`, `max_ha_value`, `smoothing`
  - Register in `_VALUE_SOURCE_MAP` as `"ha_entity"`
  - `to_dict()` / `from_dict()` / `_parse_common_fields()`

- [ ] **Store** — add `"ha_entity"` case in `ValueSourceStore.create_source()` and `update_source()`
  - Validate: `ha_source_id` must be non-empty, `entity_id` must be non-empty

- [ ] **API schemas** — `HAEntityValueSourceCreate`, `HAEntityValueSourceResponse` in `api/schemas/value_sources.py`
  - Add to `ValueSourceCreate` / `ValueSourceResponse` discriminated unions
  - Fields: `ha_source_id`, `entity_id`, `attribute` (optional), `min_ha_value`, `max_ha_value`, `smoothing`

- [ ] **API routes** — add `HAEntityValueSource` → response builder in `_RESPONSE_MAP`

- [ ] **Stream** — `HAEntityValueStream` in `core/processing/value_stream.py`
  - `start()`: acquire HA runtime via `ha_manager.acquire(ha_source_id)`
  - `get_value()`: read `ha_manager.get_state(ha_source_id, entity_id)` → extract state or attribute → clamp/normalize to [0,1] via min/max range → apply EMA smoothing
  - `stop()`: release HA runtime
  - `update_source()`: hot-update parameters
  - Add to `ValueStreamManager._create_stream()`

### Frontend

- [ ] **TypeScript type** — `HAEntityValueSource` interface in `types.ts`
  - `source_type: 'ha_entity'`, `return_type: 'float'`
  - Fields: `ha_source_id`, `entity_id`, `attribute`, `min_ha_value`, `max_ha_value`, `smoothing`
  - Add to `ValueSourceType` union and `ValueSource` union

- [ ] **Icon** — add `ha_entity: _svg(P.home)` to `_valueSourceTypeIcons` in `icons.ts`

- [ ] **i18n** — add keys in `en.json`:
  - `value_source.type.ha_entity`: "Home Assistant Entity"
  - `value_source.type.ha_entity.desc`: "Reads value from a Home Assistant sensor or entity attribute"
  - `value_source.ha_source`: "HA Connection:"
  - `value_source.entity_id`: "Entity:"
  - `value_source.attribute`: "Attribute (optional):"
  - `value_source.min_ha_value`: "Min HA Value:"
  - `value_source.max_ha_value`: "Max HA Value:"

- [ ] **Editor modal** — add `ha_entity` section to `value-source-editor.html`
  - HA connection selector (EntitySelect from HA sources cache)
  - Entity selector (EntitySelect populated from HA entities endpoint)
  - Attribute text input (optional)
  - Min/Max HA value range inputs
  - Smoothing slider

- [ ] **Editor logic** — add `ha_entity` handler in `value-sources.ts`
  - `onValueSourceTypeChange()`: show/hide ha_entity section
  - `_typeHandlers['ha_entity']`: load/reset/getPayload
  - EntitySelect for HA source + EntitySelect for entity (refreshes when HA source changes)
  - Auto-name: "{entity_friendly_name}" or "{entity_id}"

- [ ] **Card renderer** — show HA source link + entity ID + attribute (if set) + range
- [ ] **VS_TYPE_KEYS** — add `'ha_entity'` to the array

---

## Feature 2: Lerp Color Value Source (`gradient_map`)

A color value source that maps a numeric value source's output through a color gradient. Given a float value source (0..1), interpolates the color at that position in a user-defined gradient.

### Configuration
- `value_source_id: str` — reference to a float-returning value source (EntitySelect)
- `stops: List[ColorStop]` — gradient color stops `[{position: float, color: [R,G,B]}]` (reuse existing `ColorStop` model from color strip sources)
- `easing: str` — interpolation mode: "linear", "step" (reuse existing easing modes)
- `return_type: "color"` — always color

### Backend

- [ ] **Storage model** — `GradientMapValueSource` subclass in `storage/value_source.py`
  - Fields: `value_source_id`, `stops` (list of dicts with `position` + `color`), `easing`
  - Register in `_VALUE_SOURCE_MAP` as `"gradient_map"`

- [ ] **Store** — add `"gradient_map"` case in `create_source()` / `update_source()`
  - Validate: at least 2 stops, `value_source_id` non-empty

- [ ] **API schemas** — `GradientMapValueSourceCreate`, `GradientMapValueSourceResponse`
  - Reuse `ColorStop` schema from color_strip_sources schemas (or define minimal version)
  - Add to discriminated unions

- [ ] **API routes** — add to `_RESPONSE_MAP`

- [ ] **Stream** — `GradientMapValueStream` in `value_stream.py`
  - `start()`: acquire the referenced value stream via `ValueStreamManager.acquire(value_source_id)`
  - `get_value()`: return BT.601 luminance of current color
  - `get_color()`: call `inner_stream.get_value()` → interpolate through gradient stops → return RGB tuple
  - Reuse `_compute_gradient_colors()` logic from color_strip_stream.py (or a shared helper for single-point interpolation)
  - `stop()`: release inner value stream
  - `update_source()`: hot-update stops/easing, re-acquire if value_source_id changed

### Frontend

- [ ] **TypeScript type** — `GradientMapValueSource` interface
  - `source_type: 'gradient_map'`, `return_type: 'color'`
  - Fields: `value_source_id`, `stops: ColorStop[]`, `easing`

- [ ] **Icon** — add `gradient_map: _svg(P.rainbow)` to `_valueSourceTypeIcons`

- [ ] **i18n** — add keys:
  - `value_source.type.gradient_map`: "Gradient Map"
  - `value_source.type.gradient_map.desc`: "Maps a numeric value through a color gradient"
  - `value_source.input_source`: "Input Value Source:"
  - `value_source.gradient_stops`: "Gradient:"
  - `value_source.easing`: "Interpolation:"

- [ ] **Editor modal** — add `gradient_map` section
  - Value source selector (EntitySelect from float value sources)
  - Gradient stop editor (reuse gradient stop UI from CSS editor if possible, or build minimal version: list of position + color picker rows)
  - Easing selector (IconSelect: linear, step)
  - Live gradient preview bar (CSS linear-gradient from stops)

- [ ] **Editor logic** — `_typeHandlers['gradient_map']`: load/reset/getPayload
- [ ] **Card renderer** — CSS gradient preview bar + input source link + stop count
- [ ] **VS_TYPE_KEYS** — add `'gradient_map'`

---

## Feature 3: CSS Extraction Color Value Source (`css_extract`)

A color value source that extracts a single color from a color strip source by averaging a range of LEDs. Useful for deriving a single color signal from an existing color strip.

### Configuration
- `color_strip_source_id: str` — reference to a color strip source (EntitySelect)
- `led_start: int` — start of LED range (0-based, optional, default 0)
- `led_end: int` — end of LED range (exclusive, optional, default -1 = whole strip)
- `return_type: "color"` — always color

### Backend

- [ ] **Storage model** — `CSSExtractValueSource` subclass in `storage/value_source.py`
  - Fields: `color_strip_source_id`, `led_start`, `led_end`
  - Register as `"css_extract"`

- [ ] **Store** — add `"css_extract"` case in `create_source()` / `update_source()`
  - Validate: `color_strip_source_id` non-empty

- [ ] **API schemas** — `CSSExtractValueSourceCreate`, `CSSExtractValueSourceResponse`
  - Add to discriminated unions

- [ ] **API routes** — add to `_RESPONSE_MAP`

- [ ] **Stream** — `CSSExtractValueStream` in `value_stream.py`
  - `start()`: acquire color strip stream via `ColorStripStreamManager.acquire(color_strip_source_id, led_count=needed)`
  - `get_color()`: read strip colors → average the specified LED range → return single RGB tuple
  - `get_value()`: BT.601 luminance of extracted color
  - `stop()`: release color strip stream
  - `update_source()`: hot-update range, re-acquire if source changed
  - **Note**: Needs access to `ColorStripStreamManager` — may need to inject it into `ValueStreamManager` or pass via constructor

### Frontend

- [ ] **TypeScript type** — `CSSExtractValueSource` interface
  - `source_type: 'css_extract'`, `return_type: 'color'`
  - Fields: `color_strip_source_id`, `led_start`, `led_end`

- [ ] **Icon** — add `css_extract: _svg(P.eyedropper)` (or `P.pipette` if available, else `P.palette`)

- [ ] **i18n** — add keys:
  - `value_source.type.css_extract`: "Strip Color Extract"
  - `value_source.type.css_extract.desc`: "Extracts a single color from a color strip source"
  - `value_source.color_strip_source`: "Color Strip Source:"
  - `value_source.led_start`: "LED Start:"
  - `value_source.led_end`: "LED End (-1 = all):"

- [ ] **Editor modal** — add `css_extract` section
  - Color strip source selector (EntitySelect from color strip sources cache)
  - LED start/end numeric inputs
  - Optional: live color preview swatch

- [ ] **Editor logic** — `_typeHandlers['css_extract']`: load/reset/getPayload
- [ ] **Card renderer** — color strip source link + LED range badge
- [ ] **VS_TYPE_KEYS** — add `'css_extract'`

---

## Feature 4: Value Source Type Filter in Icon Grid

Add a filter/category system to the value source type IconSelect so users can filter by return type or category.

### Implementation

- [ ] **Add filter tabs** above the value source type icon grid in the editor modal
  - "All" (default) — show all types
  - "Float" — show float-returning types: static, animated, audio, adaptive_time, adaptive_scene, daylight, ha_entity
  - "Color" — show color-returning types: static_color, animated_color, adaptive_time_color, gradient_map, css_extract

- [ ] **IconSelect enhancement** — either:
  - Option A: Add `groups` support to IconSelect (items grouped by category with filter tabs)
  - Option B: Filter `VS_TYPE_KEYS` before building items, with toggle buttons above the grid
  - Decision: Option B is simpler and follows existing patterns — add filter buttons that rebuild the icon grid

- [ ] **i18n** — add keys:
  - `value_source.filter.all`: "All"
  - `value_source.filter.float`: "Float"
  - `value_source.filter.color`: "Color"

---

## Implementation Order

1. **Feature 4** (filter) — smallest, unblocks better UX for the growing type list
2. **Feature 1** (ha_entity) — standalone float type, no cross-dependencies
3. **Feature 3** (css_extract) — needs ColorStripStreamManager injection
4. **Feature 2** (gradient_map) — needs float VS reference + gradient UI

## Cross-Cutting Concerns

- All new types need entries in `_VALUE_SOURCE_MAP` (backend) and `VS_TYPE_KEYS` (frontend)
- All new types need `_RESPONSE_MAP` entries in routes
- All new types need `ValueStreamManager._create_stream()` factory case
- All new types need icon in `_valueSourceTypeIcons`
- All new types need i18n keys in `en.json` (and `ru.json`, `zh.json` — can defer translations)
- `ValueSourceStore` referential integrity check on delete should verify new references (ha_entity → ha_source, gradient_map → value_source, css_extract → color_strip_source)
- Graph editor: new edge types for ha_entity → HA source node, gradient_map → value source node, css_extract → color strip node