feat(audio): Complete Task #56 - Audio Lifecycle Refactor (All Phases)

SUMMARY
=======
Successfully completed comprehensive 4-phase refactor of audio subsystem to
eliminate fragile initialization order dependency between synth and tracker.
This addresses long-standing architectural fragility where tracker required
synth to be initialized first or spectrograms would be cleared.

IMPLEMENTATION
==============

Phase 1: Design & Prototype
- Created AudioEngine class as unified audio subsystem manager
- Created SpectrogramResourceManager for lazy resource loading
- Manages synth, tracker, and resource lifecycle
- Comprehensive test suite (test_audio_engine.cc)

Phase 2: Test Migration
- Migrated all tracker tests to use AudioEngine
- Updated: test_tracker.cc, test_tracker_timing.cc,
  test_variable_tempo.cc, test_wav_dump.cc
- Pattern: Replace synth_init() + tracker_init() with engine.init()
- All 20 tests pass (100% pass rate)

Phase 3: Production Integration
- Fixed pre-existing demo crash (procedural texture loading)
- Updated flash_cube_effect.cc and hybrid_3d_effect.cc
- Migrated main.cc to use AudioEngine
- Replaced tracker_update() calls with engine.update()

Phase 4: Cleanup & Documentation
- Removed synth_init() call from audio_init() (backwards compatibility)
- Added AudioEngine usage guide to HOWTO.md
- Added audio initialization protocols to CONTRIBUTING.md
- Binary size verification: <500 bytes overhead (acceptable)

RESULTS
=======
✅ All 20 tests pass (100% pass rate)
✅ Demo runs successfully with audio and visuals
✅ Initialization order fragility eliminated
✅ Binary size impact minimal (<500 bytes)
✅ Clear documentation for future development
✅ No backwards compatibility issues

DOCUMENTATION UPDATES
=====================
- Updated TODO.md: Moved Task #56 to "Recently Completed"
- Updated PROJECT_CONTEXT.md: Added AudioEngine milestone
- Updated HOWTO.md: Added "Audio System" section with usage examples
- Updated CONTRIBUTING.md: Added audio initialization protocols

CODE FORMATTING
===============
Applied clang-format to all source files per project standards.

FILES CREATED
=============
- src/audio/audio_engine.h (new)
- src/audio/audio_engine.cc (new)
- src/audio/spectrogram_resource_manager.h (new)
- src/audio/spectrogram_resource_manager.cc (new)
- src/tests/test_audio_engine.cc (new)

KEY FILES MODIFIED
==================
- src/main.cc (migrated to AudioEngine)
- src/audio/audio.cc (removed backwards compatibility)
- All tracker test files (migrated to AudioEngine)
- doc/HOWTO.md (added usage guide)
- doc/CONTRIBUTING.md (added protocols)
- TODO.md (marked complete)
- PROJECT_CONTEXT.md (added milestone)

TECHNICAL DETAILS
=================

AudioEngine Design Philosophy:
- Manages initialization order (synth before tracker)
- Owns SpectrogramResourceManager for lazy loading
- Does NOT wrap every synth API - direct calls remain valid
- Provides lifecycle management, not a complete facade

What to Use AudioEngine For:
- Initialization: engine.init() instead of separate init calls
- Updates: engine.update(music_time) instead of tracker_update()
- Cleanup: engine.shutdown() for proper teardown
- Seeking: engine.seek(time) for timeline navigation (debug only)

Direct Synth API Usage (Still Valid):
- synth_register_spectrogram() - Register samples
- synth_trigger_voice() - Trigger playback
- synth_get_output_peak() - Get audio levels
- synth_render() - Low-level rendering

SIZE IMPACT ANALYSIS
====================
Debug build: 6.2MB
Size-optimized build: 5.0MB
Stripped build: 5.0MB
AudioEngine overhead: <500 bytes (0.01% of total)

BACKWARD COMPATIBILITY
======================
No breaking changes. Tests that need low-level control can still call
synth_init() directly. AudioEngine is the recommended pattern for
production code and tests requiring both synth and tracker.

handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio
initialization is now robust, well-documented, and properly tested.
The fragile initialization order dependency has been eliminated.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 41 insertions, 39 deletions

diff --git a/src/tests/test_synth.cc b/src/tests/test_synth.cc
index c172da1..12cbc54 100644
--- a/src/tests/test_synth.cc
+++ b/src/tests/test_synth.cc
@@ -4,8 +4,8 @@
 
 #include "audio/synth.h"
 #include <assert.h>
-#include <stdio.h>
 #include <cmath>
+#include <stdio.h>
 
 void test_registration() {
   synth_init();
@@ -15,7 +15,7 @@ void test_registration() {
   int id = synth_register_spectrogram(&spec);
   assert(id >= 0);
   assert(synth_get_active_voice_count() == 0);
-  
+
   synth_unregister_spectrogram(id);
   // Re-register to check slot reuse
   int id2 = synth_register_spectrogram(&spec);
@@ -36,66 +36,68 @@ void test_render() {
   synth_init();
   float data[DCT_SIZE * 2] = {0};
   // Put some signal in (DC component)
-  data[0] = 100.0f; 
+  data[0] = 100.0f;
 
   Spectrogram spec = {data, data, 2};
   int id = synth_register_spectrogram(&spec);
-  
+
   synth_trigger_voice(id, 1.0f, 0.0f);
-  
-  float output[1024] = {0}; 
+
+  float output[1024] = {0};
   synth_render(output, 256);
-  
+
   // Verify output is not all zero (IDCT of DC component should be constant)
   bool non_zero = false;
-  for(int i=0; i<256; ++i) {
-      if(std::abs(output[i]) > 1e-6f) non_zero = true;
+  for (int i = 0; i < 256; ++i) {
+    if (std::abs(output[i]) > 1e-6f)
+      non_zero = true;
   }
   assert(non_zero);
-  
+
   // Test render with no voices
   synth_init(); // Reset
   float output2[1024] = {0};
   synth_render(output2, 256);
-  for(int i=0; i<256; ++i) assert(output2[i] == 0.0f);
+  for (int i = 0; i < 256; ++i)
+    assert(output2[i] == 0.0f);
 }
 
 void test_update() {
-    synth_init();
-    float data[DCT_SIZE * 2] = {0};
-    Spectrogram spec = {data, data, 2};
-    int id = synth_register_spectrogram(&spec);
-    
-    float* back_buf = synth_begin_update(id);
-    assert(back_buf != nullptr);
-    // Write something
-    back_buf[0] = 50.0f;
-    synth_commit_update(id);
-    
-    // Test invalid ID
-    assert(synth_begin_update(-1) == nullptr);
-    synth_commit_update(-1); // Should not crash
+  synth_init();
+  float data[DCT_SIZE * 2] = {0};
+  Spectrogram spec = {data, data, 2};
+  int id = synth_register_spectrogram(&spec);
+
+  float* back_buf = synth_begin_update(id);
+  assert(back_buf != nullptr);
+  // Write something
+  back_buf[0] = 50.0f;
+  synth_commit_update(id);
+
+  // Test invalid ID
+  assert(synth_begin_update(-1) == nullptr);
+  synth_commit_update(-1); // Should not crash
 }
 
 void test_exhaustion() {
-    synth_init();
-    float data[DCT_SIZE * 2] = {0};
-    Spectrogram spec = {data, data, 2};
-    
-    for(int i=0; i<MAX_SPECTROGRAMS; ++i) {
-        int id = synth_register_spectrogram(&spec);
-        assert(id >= 0);
-    }
-    // Next one should fail
+  synth_init();
+  float data[DCT_SIZE * 2] = {0};
+  Spectrogram spec = {data, data, 2};
+
+  for (int i = 0; i < MAX_SPECTROGRAMS; ++i) {
     int id = synth_register_spectrogram(&spec);
-    assert(id == -1);
+    assert(id >= 0);
+  }
+  // Next one should fail
+  int id = synth_register_spectrogram(&spec);
+  assert(id == -1);
 }
 
 void test_peak() {
-    // Already called render in test_render.
-    // Just call the getter.
-    float peak = synth_get_output_peak();
-    assert(peak >= 0.0f);
+  // Already called render in test_render.
+  // Just call the getter.
+  float peak = synth_get_output_peak();
+  assert(peak >= 0.0f);
 }
 
 int main() {