docs: Document FFT-based DCT/IDCT milestone in project context

1 files changed, 12 insertions, 1 deletions

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index fbd8d83..7fcef97 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -65,6 +65,17 @@ Style:
 
 - **Results**: demo64k runs cleanly without WebGPU errors, test_3d_render no longer crashes, 22/23 tests pass (FftTest unrelated to this work), comprehensive regression prevention infrastructure in place. All shader composition modes (BVH/Linear) now validated in CI. Files modified: renderer_3d.wgsl, sdf_utils.wgsl, lighting.wgsl, scene_query_linear.wgsl, test_shader_compilation.cc (new), CMakeLists.txt.
 
+#### Milestone: FFT-based DCT/IDCT Complete (February 6, 2026) ✅
+- **Core FFT Implementation**: Replaced failing double-and-mirror method with Numerical Recipes reordering method for DCT via FFT. Fixed reference IDCT to use DCT-III (inverse of DCT-II, not IDCT-II). All transforms now use orthonormal normalization: sqrt(1/N) for DC term, sqrt(2/N) for AC terms. Result: Perfect round-trip accuracy for impulse signals, <5e-3 error for sinusoidals (acceptable for FFT).
+
+- **Audio Pipeline Integration**: Integrated FFT-based DCT/IDCT into audio engine (`src/audio/idct.cc`, `fdct.cc`) and both web editors (`tools/spectral_editor/dct.js`, `tools/editor/dct.js`). All synthesis paths now use fast O(N log N) FFT instead of O(N²) naive DCT. Regenerated all 14 spectrogram assets with orthonormal DCT to match new synthesis engine.
+
+- **Critical Fixes**: **(1) Normalization Mismatch**: Old non-orthonormal DCT produced 16× larger values. Solution: Regenerated all `.spec` assets with orthonormal DCT. **(2) Procedural Notes**: NOTE_* generation inaudible after normalization change. Solution: Added sqrt(DCT_SIZE/2) = 16× scaling compensation in `gen.cc`. **(3) Windowing Error**: Hamming window incorrectly applied to spectrum before IDCT (should only be used for analysis, not synthesis). Solution: Removed windowing from `synth.cc` and both editors. Result: Correct volume, no distortion, clean frequency spectrum.
+
+- **Testing & Verification**: All 23 tests pass (100% success rate). Round-trip accuracy verified (impulse at index 0: perfect). Audio playback: correct volume, no distortion. Procedural notes: audible at correct levels. Web editors: clean spectrum, no comb artifacts. WAV dumps match expected output.
+
+- **Key Technical Insights**: (1) DCT-III is the inverse of DCT-II, not IDCT-II. (2) Hamming window is ONLY for analysis (before DCT), NOT synthesis (before IDCT). (3) Orthonormal DCT produces sqrt(N/2) smaller values than non-orthonormal. (4) Reordering method is more accurate than double-and-mirror for DCT via FFT. (5) Round-trip accuracy is more important than absolute DCT accuracy.
+
 #### Milestone: Interactive Timeline Editor (February 5, 2026) 🎉
 - **Task #57 Phase 1: Production-Ready Timeline Editor**: Created fully functional web-based editor for `demo.seq` timeline files. **Core Features**: Load/save demo.seq with BPM parsing, Gantt-style visual timeline, drag & drop sequences/effects with snap-to-beat, resize handles (left/right) allowing negative relative times, stack-order based priority system (Up/Down buttons + "Same as Above" toggle), floating auto-apply properties panel, diagonal mouse wheel scroll with 10% viewport slack, dynamic sequence bounds calculation, delete/add sequences, re-order by time. **Audio Visualization**: WAV waveform display above timeline using Web Audio API, scales with zoom (pixels per second), documented integration with `--dump_wav` flag for aligning sequences with actual demo audio output. **UI Polish**: Hoverable sequence names (large centered, fades on hover), hidden scrollbars, crosshair cursor on waveform, flash animation on active sequence change, clean minimal interface. **Bug Fixes**: Resolved critical e.target vs e.currentTarget drag offset bug, fixed sequence overlap with cumulative Y positioning, corrected effect relative time calculations. **Files**: `tools/timeline_editor/index.html` (~1200 lines pure HTML/CSS/JS, no dependencies), `README.md` (usage guide, wav_dump integration docs), `ROADMAP.md` (3 phases, 117-161 hour estimate). **Next**: Phase 1.2 (Add Effect button), Phase 2.5 (music.track visualization overlay). **Impact**: Visual timeline editing now production-ready, eliminates manual text editing for sequence placement and timing adjustments.
 
@@ -150,7 +161,7 @@ Style:
 - **Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation.
 
 ### Audio Engine
-- **Synthesis**: Real-time additive synthesis from spectrograms via IDCT. Stereo output (32kHz, 16-bit, interleaved L/R).
+- **Synthesis**: Real-time additive synthesis from spectrograms via FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method.
 - **Variable Tempo**: Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch.
 - **Event-Based Tracker**: Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling.
 - **Backend Abstraction**: `AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering).