docs: Milestone - Shader Stability & Test Infrastructure (February 6, 2026)

## Summary

Completed critical stability improvements resolving all shader validation errors
and establishing comprehensive test infrastructure to prevent future regressions.

## Key Achievements

### 1. Demo Stability Restored
- demo64k: Runs cleanly without WebGPU errors
- test_3d_render: No longer crashes on startup
- All 22/23 tests pass (FftTest unrelated to shader work)

### 2. Critical Bugs Fixed
**Bug #1**: renderer_3d.wgsl dead code using non-existent inverse() function
  - WGSL doesn't provide matrix inverse
  - Validator checks all code paths, even unreachable ones
  - Also removed undefined in.normal reference

**Bug #2**: sdf_utils.wgsl & lighting.wgsl signature mismatch
  - get_normal_basic(obj_type: f32) → get_normal_basic(obj_params: vec4<f32>)
  - Fixed type mismatch with get_dist() calls

**Bug #3**: scene_query_linear.wgsl binding error (ROOT CAUSE)
  - Linear mode incorrectly declared binding 2 (BVH buffer)
  - Copy-paste error: Linear shader was identical to BVH shader
  - Pipeline created without binding 2 → Shader expected binding 2 → Crash
  - Fixed: Replaced BVH traversal with proper linear iteration

### 3. Test Infrastructure
Created test_shader_compilation.cc:
  - Compiles all production shaders through WebGPU
  - Validates both BVH and Linear composition modes
  - Catches syntax errors, binding mismatches, type errors
  - Would have caught all three bugs fixed in this milestone

**Test Gap Analysis**:
  - Old: test_shader_assets only checked keywords (not compilation)
  - New: Real GPU validation with wgpuDeviceCreateShaderModule
  - Result: Comprehensive regression prevention

## Files Modified
- assets/final/shaders/renderer_3d.wgsl (removed dead code)
- assets/final/shaders/sdf_utils.wgsl (fixed signature)
- assets/final/shaders/lighting.wgsl (fixed signature)
- assets/final/shaders/render/scene_query_linear.wgsl (removed BVH code)
- src/tests/test_shader_compilation.cc (new test)
- CMakeLists.txt (added new test)
- TODO.md (documented completion)
- PROJECT_CONTEXT.md (added milestone)

## Impact

✅ Production stability: No crashes or WebGPU errors
✅ Test coverage: Shader compilation validated in CI
✅ Developer experience: Clear error messages on shader issues
✅ Regression prevention: Future shader bugs caught automatically

## Related Work

This milestone complements recent build system improvements (Task C) where
shader asset dependency tracking was fixed. Together, these ensure:
1. Shader edits trigger correct rebuilds (build system)
2. Invalid shaders caught before runtime (this milestone)

---

handoff(Claude): Shader stability milestone complete. Demo runs cleanly,
comprehensive test infrastructure prevents future shader regressions. All
shader composition modes (BVH/Linear) validated. 22/23 tests passing.

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

1 files changed, 7 insertions, 0 deletions

diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 4d1fa35..fbd8d83 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -58,6 +58,13 @@ Style:
 #### Milestone: Build System Optimization (February 6, 2026)
 - **Task C: CMake Dependency Graph Optimization**: Resolved critical build correctness bugs and improved developer iteration speed. **Header Split**: Refactored monolithic `asset_manager.h` (61 lines) into three focused headers: `asset_manager_dcl.h` (forward declarations for AssetId), `asset_manager.h` (core GetAsset/DropAsset API), and `asset_manager_utils.h` (typed helpers for TextureAsset/MeshAsset). Updated 17 source files to use appropriate headers. **Asset Dependency Tracking**: Implemented file-level dependency tracking for all 42 demo assets and 17 test assets. CMake now correctly tracks individual `.wgsl` shaders, `.spec` audio files, and `.obj` mesh files. **Critical Bug Fixed**: Changing shader files was NOT triggering asset regeneration, resulting in stale code in binaries. Developers had to manually `touch demo_assets.txt` as workaround. Now works correctly. **Performance**: Editing TextureAsset/MeshAsset helpers improved from 4.82s to 2.01s (58% faster). Shader edits now trigger correct 3.5s rebuild (was 0.28s with no rebuild - incorrect). **Implementation**: Added `parse_asset_list()` CMake function that parses `demo_assets.txt` format (`ASSET_NAME, COMPRESSION, FILENAME, DESC`) and extracts individual file paths for dependency tracking. All 20 tests pass. Zero functionality regressions.
 
+#### Milestone: Critical Shader Stability & Test Infrastructure (February 6, 2026) ✅
+- **Shader Crash Resolution**: Fixed three critical WGSL validation errors causing demo64k and test_3d_render to crash on startup. **Bug 1 (renderer_3d.wgsl)**: Removed dead code using non-existent `inverse()` function - WGSL doesn't provide matrix inverse, and validator checks all code paths even unreachable ones. Also removed reference to undefined `in.normal` vertex input. **Bug 2 (sdf_utils.wgsl, lighting.wgsl)**: Fixed `get_normal_basic()` function signature mismatch - changed from `obj_type: f32` to `obj_params: vec4<f32>` to match `get_dist()` calls. **Bug 3 (scene_query_linear.wgsl - ROOT CAUSE)**: Fixed linear scene query mode incorrectly declaring binding 2 (BVH storage buffer). Linear version was identical to BVH version due to copy-paste error. Replaced BVH traversal with proper linear object iteration loop. **Impact**: When `use_bvh=false`, pipeline created without binding 2, but shader expected it → validation error → crash.
+
+- **Comprehensive Shader Compilation Tests**: Created `test_shader_compilation.cc` to prevent regression. Test compiles all production shaders through WebGPU (`wgpuDeviceCreateShaderModule`), validates both BVH and Linear composition modes using `ShaderComposer`, catches WGSL syntax errors, binding mismatches, type errors, and function signature issues. **Test Gap Analysis**: Existing `test_shader_assets.cc` only checked for keywords (`@vertex`, `fn`, etc.) without actual compilation - would NOT have caught any of the three bugs. New test fills this gap with real GPU validation. **Graceful Degradation**: Test handles platforms where WebGPU device unavailable by skipping GPU tests but still validating shader composition.
+
+- **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: 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.