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, 10 insertions, 0 deletions

diff --git a/TODO.md b/TODO.md
index 105be30..dfa2b20 100644
--- a/TODO.md
+++ b/TODO.md
@@ -4,6 +4,16 @@ This file tracks prioritized tasks with detailed attack plans.
 
 ## Recently Completed (February 6, 2026)
 
+- [x] **Critical Shader Bug Fixes & Test Infrastructure** (February 6, 2026)
+    - [x] **Shader Validation Errors**: Fixed three critical WGSL bugs causing demo64k and test_3d_render crashes:
+      - Removed dead code using non-existent `inverse()` function in renderer_3d.wgsl
+      - Fixed `get_normal_basic()` signature mismatch in sdf_utils.wgsl and lighting.wgsl (obj_type: f32 → obj_params: vec4<f32>)
+      - Fixed scene_query_linear.wgsl incorrectly declaring binding 2 (BVH buffer) - was identical to BVH version due to copy-paste error
+    - [x] **Root Cause**: Linear shader mode expected no binding 2, but shader declared it, causing pipeline/shader mismatch
+    - [x] **New Test Coverage**: Created `test_shader_compilation.cc` that compiles all production shaders through WebGPU, tests both BVH and Linear composition modes, validates WGSL syntax/bindings/types
+    - [x] **Test Gap Analysis**: Existing test_shader_assets only checked keywords, not actual compilation. New test would have caught all three bugs.
+    - **Result**: demo64k runs without WebGPU errors, test_3d_render no longer crashes, 22/23 tests pass (FftTest unrelated), comprehensive regression prevention
+
 - [x] **Task C: Build System Optimization** (February 6, 2026)
     - [x] **Header Split**: Refactored `asset_manager.h` into `asset_manager_dcl.h` (forward declarations), `asset_manager.h` (core API), and `asset_manager_utils.h` (typed helpers for TextureAsset/MeshAsset).
     - [x] **Asset Dependency Tracking**: Added file-level dependencies for all assets (.wgsl shaders, .spec audio, .obj meshes). CMake now tracks 42 demo assets + 17 test assets individually.