---
phase: 03-communication-protocol
plan: "02"
subsystem: animations
tags: [animation, rendering, tdd, python, fire2012, rainbow, chase, strobe, pulse]
dependency_graph:
  requires: []
  provides: [lightsync.animations, ANIMATION_REGISTRY, create_animation, AnimationBase]
  affects: [phase-04-timeline-editor, phase-05-live-execution]
tech_stack:
  added: [colorsys (stdlib), math (stdlib), abc (stdlib), random (stdlib)]
  patterns: [ABC inheritance, factory registry, TDD red-green, pure functions]
key_files:
  created:
    - lightsync/animations/__init__.py
    - lightsync/animations/base.py
    - lightsync/animations/solid_color.py
    - lightsync/animations/chase.py
    - lightsync/animations/pulse.py
    - lightsync/animations/rainbow.py
    - lightsync/animations/strobe.py
    - lightsync/animations/color_wipe.py
    - lightsync/animations/fire.py
    - tests/test_animations.py
  modified: []
decisions:
  - "chase reverse detection uses offset-not-multiple-of-period for reliable test assertion"
  - "FireAnimation lazy-initializes heat array per led_count to support variable strip lengths"
  - "speed parameter mapped differently per animation: pulse maps to period, strobe to Hz, chase/wipe to px/sec"
metrics:
  duration: "3 min"
  completed: "2026-04-06"
  tasks_completed: 1
  files_changed: 10
requirements: [ANI-01, ANI-02]
---

# Phase 03 Plan 02: Animation Library Summary

**One-liner:** 7 animation types (solid_color, chase, pulse, rainbow, strobe, color_wipe, fire) as pure renderers with AnimationBase ABC, ANIMATION_REGISTRY, and create_animation() factory — all via TDD red-green cycle.

## What Was Built

The `lightsync/animations/` package provides all animation rendering for the LightSync system. Animations are pure computation: `render(t, led_count) -> list[tuple]`. No I/O, no networking — just pixel data generation that the protocol layer (Plan 01) encodes and sends.

### AnimationBase ABC

`lightsync/animations/base.py` defines the contract:
- `render(t: float, led_count: int) -> list[tuple]` — render at time t, returns list of (R,G,B) tuples
- `from_params(params: dict) -> AnimationBase` — construct from CueModel.params dict

### 7 Animation Types

| Animation | Algorithm | Key Params |
|-----------|-----------|------------|
| solid_color | Uniform fill | color, white |
| chase | Moving segment, modulo pattern | color, bg_color, speed, size, spacing, reverse |
| pulse | Sine-wave brightness oscillation | color, speed (maps to period 0.1-5.0s), min/max_brightness |
| rainbow | HSV hue cycle via colorsys | speed, period |
| strobe | On/off at 1-20 Hz | color, speed, duty_cycle |
| color_wipe | Progressive fill from start/end | color, speed, reverse |
| fire | Fire2012: cool+drift+spark+heat-color | cooling, sparking, speed |

### Registry and Factory

`ANIMATION_REGISTRY` maps all 7 names to classes. `create_animation(name, params)` raises `ValueError` for unknown types.

## TDD Execution

**RED phase:** `tests/test_animations.py` (24 tests) committed before any implementation. Tests failed with `ModuleNotFoundError`.

**GREEN phase:** Implemented all 9 files. One test required a fix: `test_chase_reverse` initially used `t=1.5` which caused `offset % period == 0`, making fwd and rev identical. Fixed to use `t=0.05` (offset=3, not multiple of period=10).

**Result:** 24/24 tests passing.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Chase reverse test used symmetrical t value**
- **Found during:** TDD GREEN phase verification
- **Issue:** At t=1.5 with speed=1.0, offset=90 which is a multiple of period=10, making forward and reverse chase produce identical pixel patterns
- **Fix:** Changed test t from 1.5 to 0.05 (offset=3, not multiple of period), which reliably distinguishes fwd vs reverse
- **Files modified:** tests/test_animations.py
- **Commit:** f4da956

## Known Stubs

None. All 7 animation types fully implemented and rendering real pixel data.

## Self-Check: PASSED

Files:
- FOUND: lightsync/animations/__init__.py
- FOUND: lightsync/animations/base.py
- FOUND: lightsync/animations/solid_color.py
- FOUND: lightsync/animations/chase.py
- FOUND: lightsync/animations/pulse.py
- FOUND: lightsync/animations/rainbow.py
- FOUND: lightsync/animations/strobe.py
- FOUND: lightsync/animations/color_wipe.py
- FOUND: lightsync/animations/fire.py
- FOUND: tests/test_animations.py

Commits:
- 920243f: test(03-02): add failing tests for animation library
- f4da956: feat(03-02): implement animation library — 7 types with registry and factory