docs(03-03): complete UDP simulator and FastAPI integration plan

- Create 03-03-SUMMARY.md: simulator, e2e tests, lifespan integration
- Update STATE.md: advance plan, 100% progress, record decisions
- Update ROADMAP.md: phase 03 marked Complete (3/3 plans)
- Mark UDP-04 requirement complete in REQUIREMENTS.md

.planning/REQUIREMENTS.md

@@ -50,7 +50,7 @@
 - [x] **UDP-01**: Animation command packet: device ID, animation type, params — sent when block starts
 - [x] **UDP-02**: Raw pixel frame packet: WLED DRGB/DNRGB/DRGBW protocol — used for AI-generated sequences
 - [x] **UDP-03**: Multi-packet framing for frames >MTU (SK6812 300 LEDs RGBW = 1200 bytes, exceeds WiFi MTU)
-- [ ] **UDP-04**: Software UDP receiver/simulator for testing without physical hardware
+- [x] **UDP-04**: Software UDP receiver/simulator for testing without physical hardware
 
 ### Automatic Sync
 

.planning/ROADMAP.md

@@ -14,7 +14,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 
 - [x] **Phase 1: Foundation** - FastAPI skeleton, show file schema (Pydantic), device registry, terminal-aesthetic frontend shell (gap closure in progress) (completed 2026-04-05)
 - [x] **Phase 2: Audio Engine** - MPV IPC bridge, waveform rendering, playback controls, Windows timer fix (completed 2026-04-06)
-- [ ] **Phase 3: Communication Protocol** - UDP packet spec, DRGB/DNRGB/DRGBW encoders, animation library, software simulator
+- [x] **Phase 3: Communication Protocol** - UDP packet spec, DRGB/DNRGB/DRGBW encoders, animation library, software simulator (completed 2026-04-06)
 - [ ] **Phase 4: Timeline Editor** - DAW UI (tracks, drag-place blocks, resize, delete), undo/redo, beat detection, snap-to-beat
 - [ ] **Phase 5: Live Show Execution** - End-to-end show playback, seek-safe cue scheduling, show save/load, keyboard shortcuts, live preview
 - [ ] **Phase 6: AI Sync** - YouTube loading, AI-assisted show generation, beat calibration UI, structural segmentation
@@ -74,7 +74,7 @@ Plans:
 Plans:
 - [x] 03-01-PLAN.md — Protocol encoders (DRGB/DRGBW/DNRGB + animation command), UDP sender, device stub completion
 - [x] 03-02-PLAN.md — Animation library (7 built-in types with AnimationBase ABC, registry, factory)
-- [ ] 03-03-PLAN.md — UDP simulator, FastAPI integration, end-to-end protocol validation
+- [x] 03-03-PLAN.md — UDP simulator, FastAPI integration, end-to-end protocol validation
 
 ### Phase 4: Timeline Editor
 **Goal**: The timeline editor is fully functional — users can place, move, resize, and delete animation blocks on per-device tracks with beat-snapping and undo/redo
@@ -154,7 +154,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
 |-------|----------------|--------|-----------|
 | 1. Foundation | 4/4 | Complete   | 2026-04-05 |
 | 2. Audio Engine | 3/3 | Complete   | 2026-04-06 |
-| 3. Communication Protocol | 2/3 | In Progress|  |
+| 3. Communication Protocol | 3/3 | Complete   | 2026-04-06 |
 | 4. Timeline Editor | 0/4 | Not started | - |
 | 5. Live Show Execution | 0/3 | Not started | - |
 | 6. AI Sync | 0/3 | Not started | - |

.planning/STATE.md

@@ -2,15 +2,15 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-status: executing
+status: verifying
-stopped_at: Completed 03-communication-protocol/03-02-PLAN.md
+stopped_at: Completed 03-communication-protocol/03-03-PLAN.md
-last_updated: "2026-04-06T21:48:33.912Z"
+last_updated: "2026-04-06T21:52:27.756Z"
 last_activity: 2026-04-06
 progress:
   total_phases: 7
-  completed_phases: 2
+  completed_phases: 3
   total_plans: 10
-  completed_plans: 9
+  completed_plans: 10
   percent: 0
 ---
 
@@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-04-05)
 
 Phase: 03 (communication-protocol) — EXECUTING
 Plan: 3 of 3
-Status: Ready to execute
+Status: Phase complete — ready for verification
 Last activity: 2026-04-06
 
 Progress: [░░░░░░░░░░] 0%
@@ -61,6 +61,7 @@ Progress: [░░░░░░░░░░] 0%
 | Phase 02-audio-engine P03 | 4 | 9 tasks | 8 files |
 | Phase 03-communication-protocol P01 | 4min | 2 tasks | 8 files |
 | Phase 03-communication-protocol P02 | 3min | 1 tasks | 10 files |
+| Phase 03-communication-protocol P03 | 2min | 2 tasks | 3 files |
 
 ## Accumulated Context
 
@@ -95,6 +96,8 @@ Recent decisions affecting current work:
 - [Phase 03-communication-protocol]: UDPSender uses single shared asyncio DatagramTransport — no socket pool needed for UDP multi-device sends
 - [Phase 03-communication-protocol]: Chase reverse test uses offset-not-multiple-of-period for reliable assertion
 - [Phase 03-communication-protocol]: FireAnimation lazy-initializes heat array per led_count to support variable strip lengths
+- [Phase 03-communication-protocol]: asyncio.run() test pattern chosen over pytest-asyncio — not installed, plan provided this fallback
+- [Phase 03-communication-protocol]: UDPSender stopped before registry.save() in shutdown — orderly teardown, no sends after socket close
 
 ### Pending Todos
 
@@ -108,8 +111,8 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-06T21:48:33.906Z
+Last session: 2026-04-06T21:52:27.749Z
-Stopped at: Completed 03-communication-protocol/03-02-PLAN.md
+Stopped at: Completed 03-communication-protocol/03-03-PLAN.md
 Resume file: None
 
 Next action: `/gsd:plan-phase 1`

.planning/phases/03-communication-protocol/03-03-SUMMARY.md

@@ -0,0 +1,75 @@
+---
+phase: 03-communication-protocol
+plan: "03"
+subsystem: protocol
+tags: [udp, simulator, e2e-testing, fastapi, tdd]
+dependency_graph:
+  requires: ["03-01", "03-02"]
+  provides: ["UDP simulator with packet logging", "UDPSender in FastAPI lifespan", "end-to-end protocol tests"]
+  affects: ["lightsync/main.py", "lightsync/protocol/simulator.py", "tests/test_e2e_protocol.py"]
+tech_stack:
+  added: ["asyncio.DatagramProtocol for UDP simulation"]
+  patterns: ["TDD RED-GREEN", "asyncio.run() in tests (no pytest-asyncio)", "dataclass for structured packet logs"]
+key_files:
+  created:
+    - lightsync/protocol/simulator.py
+    - tests/test_e2e_protocol.py
+  modified:
+    - lightsync/main.py
+decisions:
+  - "asyncio.run() test pattern chosen over pytest-asyncio — not installed, plan explicitly provided this fallback"
+  - "SimulatorProtocol uses port=0 in tests — OS assigns free port, read back via get_extra_info('sockname')[1]"
+  - "UDPSender stopped before registry.save() in shutdown — orderly teardown, no sends after socket close"
+metrics:
+  duration: "2 min"
+  completed_date: "2026-04-06"
+  tasks_completed: 2
+  files_created: 2
+  files_modified: 1
+---
+
+# Phase 03 Plan 03: UDP Simulator and FastAPI Integration Summary
+
+**One-liner:** Async UDP simulator parses all 4 WLED packet types (DRGB/DRGBW/DNRGB/ANIM_CMD) with structured packet logging; UDPSender integrated into FastAPI lifespan; 7 end-to-end tests prove full animation-to-wire pipeline.
+
+## What Was Built
+
+### Task 1: UDP Simulator with Packet Logging (TDD)
+
+`lightsync/protocol/simulator.py` — a `SimulatorProtocol(asyncio.DatagramProtocol)` that:
+- Parses DRGB (0x02): extracts `led_count = (len(data)-2) // 3`
+- Parses DRGBW (0x03): extracts `led_count = (len(data)-2) // 4`
+- Parses DNRGB (0x04): extracts big-endian uint16 start index at bytes 2-3, `led_count = (len(data)-4) // 3`
+- Parses ANIM_CMD (0xAC): calls `decode_animation_cmd`, stores result in `PacketLog.decoded`
+- Stores all received packets as `PacketLog` dataclasses for test assertions
+
+`tests/test_e2e_protocol.py` — 7 end-to-end tests using `asyncio.run()`:
+- `test_e2e_drgb_10_pixels` — DRGB 10 pixels, led_count verified
+- `test_e2e_drgbw_10_pixels` — DRGBW 10 pixels, led_count verified
+- `test_e2e_dnrgb_600_pixels` — 600-LED frame splits into 2 packets, start_indices 0 and 489
+- `test_e2e_animation_cmd_chase` — animation command round-trip, decoded animation=="chase"
+- `test_e2e_full_pipeline` — solid_color render -> encode_drgb -> send -> 20-LED DRGB frame verified
+- `test_e2e_sk6812_rgbw_pipeline` — solid_color -> RGBW encode -> DRGBW 15-LED frame verified
+- `test_simulator_standalone_import` — run_simulator importable without error
+
+TDD flow: RED commit (failing import) -> GREEN commit (simulator implemented, all 7 pass).
+
+### Task 2: UDPSender into FastAPI Lifespan
+
+`lightsync/main.py` updated:
+- Added `from lightsync.protocol.udp_sender import UDPSender` import
+- Lifespan startup: `UDPSender()` created, `await udp_sender.start()`, assigned to `app.state.udp_sender`
+- Lifespan shutdown: `await app.state.udp_sender.stop()` before `await registry.save()`
+- All existing lifespan code unchanged (beats cache, registry, show_store)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — all implemented functionality is fully wired.
+
+## Self-Check: PASSED
+
+See below.