# Implementation Plan: Update HSBK RGB Conversion to Float

**Track ID:** hsbk-rgb-float_20260318
**Spec:** [spec.md](./spec.md)
**Created:** 2026-03-18
**Status:** [ ] Not Started

## Overview

Update `HSBK.from_rgb()` and `to_rgb()` from int (0–255) to float (0.0–1.0), then cascade the change through the Colors enum, docstrings, callers, and tests. Finally, consolidate the fireworks effect's redundant private helpers.

## Phase 1: Core API Change

Update `from_rgb()` and `to_rgb()` signatures and their direct tests.

### Tasks

- [ ] Task 1.1: Update `test_color.py` tests to use float inputs/outputs (red phase — tests will fail)
- [ ] Task 1.2: Update `HSBK.from_rgb()` to accept `float` (0.0–1.0), remove int validation and `/ 255` normalization, remove rounding of hue/sat/bri
- [ ] Task 1.3: Update `HSBK.to_rgb()` to return `tuple[float, float, float]` (0.0–1.0), remove `* 255` denormalization and `int(round())`
- [ ] Task 1.4: Update docstrings and examples on both methods

### Verification

- [ ] `test_color.py` passes with float-based assertions
- [ ] Round-trip error is within floating-point epsilon

## Phase 2: Colors Enum

Convert all ~148 `Colors` entries from int to float values.

### Tasks

- [ ] Task 2.1: Convert all `Colors` enum entries from `from_rgb(int, int, int)` to `from_rgb(float, float, float)` by dividing each value by 255
- [ ] Task 2.2: Verify `Colors` enum values are correct (spot-check primaries, grays, edge cases)

### Verification

- [ ] All existing `Colors`-related tests pass
- [ ] Pyright passes on `color.py`

## Phase 3: Caller Updates

Update all docstrings, effect code, and remaining tests that reference the old int API.

### Tasks

- [ ] Task 3.1: Update docstring examples in `light.py`, `multizone.py`, `matrix.py`, `api.py`, `effects/base.py`, `effects/pulse.py`
- [ ] Task 3.2: Update `test_effects/test_pulse.py` to use float values
- [ ] Task 3.3: Run full test suite and fix any remaining breakage

### Verification

- [ ] Full test suite passes
- [ ] `ruff check` and `ruff format` pass

## Phase 4: Fireworks Consolidation

Replace fireworks private RGB helpers with the now-equivalent `HSBK` methods.

### Tasks

- [ ] Task 4.1: Replace `_hsb_to_rgb()` calls with `HSBK.to_rgb()` (via temporary HSBK instance or extracted method)
- [ ] Task 4.2: Replace `_rgb_to_hsb()` calls with `HSBK.from_rgb()`
- [ ] Task 4.3: Remove `_hsb_to_rgb()` and `_rgb_to_hsb()` functions and `_HUE_SEXTANTS` constant
- [ ] Task 4.4: Run fireworks tests to confirm no regressions

### Verification

- [ ] Fireworks tests pass with identical behavior
- [ ] No private RGB helpers remain in `fireworks.py`

## Final Verification

- [ ] All acceptance criteria met
- [ ] `uv run --frozen pytest` — full suite passes
- [ ] `uv run pyright` — no type errors
- [ ] `uv run ruff check . && uv run ruff format --check .` — clean
- [ ] Ready for review

---

_Generated by Conductor. Tasks will be marked [~] in progress and [x] complete._
