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>

0 files changed, 0 insertions, 0 deletions