fix: Resolve CNN effect black screen bug (framebuffer capture + uniforms)

Two bugs causing black screen when CNN post-processing activated:

1. Framebuffer capture timing: Capture ran inside post-effect loop after
   ping-pong swaps, causing layers 1+ to capture wrong buffer. Moved
   capture before loop to copy framebuffer_a once before post-chain starts.

2. Missing uniforms update: CNNEffect never updated uniforms_ buffer,
   leaving uniforms.resolution uninitialized (0,0). UV calculation
   p.xy/uniforms.resolution produced NaN, causing all texture samples
   to return black. Added uniforms update in update_bind_group().

Files modified:
- src/gpu/effect.cc: Capture before post-chain (lines 308-346)
- src/gpu/effects/cnn_effect.cc: Add uniforms update (lines 132-142)
- workspaces/main/shaders/cnn/cnn_layer.wgsl: Remove obsolete comment
- doc/CNN_DEBUG.md: Historical debugging doc
- CLAUDE.md: Reference CNN_DEBUG.md in historical section

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

5 files changed, 97 insertions, 35 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 3d41cb7..a52dfce 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,6 +52,7 @@
 #   doc/PLATFORM_ANALYSIS.md
 #   doc/PLATFORM_SIDE_QUEST_SUMMARY.md
 #   doc/PEAK_FIX_SUMMARY.md
+#   doc/CNN_DEBUG.md - CNN post-processing binding bug resolution
 #
 # Agent Handoffs:
 #   doc/HANDOFF_CLAUDE.md
diff --git a/doc/CNN_DEBUG.md b/doc/CNN_DEBUG.md
new file mode 100644
index 0000000..dba0b60
--- /dev/null
+++ b/doc/CNN_DEBUG.md
@@ -0,0 +1,43 @@
+# CNN Effect Black Screen Bug - Resolution (2026-02)
+
+## Problem
+CNN post-processing effect showed black screen when activated at 11.50s, despite scene rendering correctly before CNN started.
+
+## Root Causes
+
+### Bug 1: Framebuffer Capture Timing
+**Location**: `src/gpu/effect.cc`
+**Issue**: Capture ran INSIDE post-effect loop after ping-pong buffer swaps. CNN layers 1+ captured wrong buffer (output being written to, not scene).
+**Fix**: Moved capture before loop starts (lines 308-346). Capture now copies `framebuffer_a` to `captured_frame` auxiliary texture ONCE before any post-effects run.
+
+### Bug 2: Missing Uniforms Update ⚠️ CRITICAL
+**Location**: `src/gpu/effects/cnn_effect.cc`
+**Issue**: `CNNEffect::update_bind_group()` never updated `uniforms_` buffer. `uniforms.resolution` uninitialized (0,0 or garbage) → UV calculation `p.xy / uniforms.resolution` produced NaN → all texture samples black.
+**Fix**: Added uniforms update before bind group creation (lines 132-142):
+```cpp
+const CommonPostProcessUniforms u = {
+    .resolution = {(float)width_, (float)height_},
+    .aspect_ratio = (float)width_ / (float)height_,
+    .time = 0.0f,
+    .beat = 0.0f,
+    .audio_intensity = 0.0f,
+};
+uniforms_.update(ctx_.queue, u);
+```
+
+## Key Lessons
+
+1. **All post-process effects MUST update `uniforms_` buffer** - Required for UV calculations and shader parameters
+2. **Framebuffer capture timing is critical** - Must happen before post-chain ping-pong starts
+3. **Uninitialized uniforms cause silent failures** - Produces black output without validation errors
+4. **Post-effects must render or chain breaks** - `loadOp=Load` preserves previous (black) content if no draw call executes
+
+## Files Modified
+- `src/gpu/effect.cc`: Lines 308-346 (capture timing)
+- `src/gpu/effects/cnn_effect.cc`: Lines 132-142 (uniforms update)
+
+## Verification
+Test: `demo64k --seek 11.5`
+- ✅ Scene visible with RotatingCube
+- ✅ CNN stylization applied
+- ✅ All 3 layers process with correct original texture reference
diff --git a/src/gpu/effect.cc b/src/gpu/effect.cc
index b50acce..fba3353 100644
--- a/src/gpu/effect.cc
+++ b/src/gpu/effect.cc
@@ -293,6 +293,45 @@ void MainSequence::render_frame(float global_time, float beat, float peak,
   wgpuRenderPassEncoderEnd(scene_pass);
 
   // 3. Post Chain
+
+  // Capture framebuffer ONCE before post-processing chain
+  bool needs_capture = false;
+  for (const SequenceItem* item : post_effects) {
+    PostProcessEffect* pp = (PostProcessEffect*)(item->effect.get());
+    if (pp->needs_framebuffer_capture()) {
+      needs_capture = true;
+      break;
+    }
+  }
+
+  if (needs_capture) {
+    WGPUTextureView captured_view = get_auxiliary_view("captured_frame");
+    if (captured_view) {
+      WGPURenderPassColorAttachment capture_attachment = {};
+      capture_attachment.view = captured_view;
+      capture_attachment.resolveTarget = nullptr;
+      capture_attachment.loadOp = WGPULoadOp_Clear;
+      capture_attachment.storeOp = WGPUStoreOp_Store;
+      capture_attachment.clearValue = {0.0f, 0.0f, 0.0f, 1.0f};
+#if !defined(DEMO_CROSS_COMPILE_WIN32)
+      capture_attachment.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
+#endif
+      WGPURenderPassDescriptor capture_desc = {
+          .colorAttachmentCount = 1, .colorAttachments = &capture_attachment};
+      WGPURenderPassEncoder capture_pass =
+          wgpuCommandEncoderBeginRenderPass(encoder, &capture_desc);
+      wgpuRenderPassEncoderSetViewport(capture_pass, 0.0f, 0.0f,
+                                       (float)width_, (float)height_, 0.0f, 1.0f);
+
+      PostProcessEffect* passthrough =
+          (PostProcessEffect*)passthrough_effect_.get();
+      passthrough->update_bind_group(framebuffer_view_a_);
+      passthrough->render(capture_pass, 0, 0, 0, aspect_ratio);
+
+      wgpuRenderPassEncoderEnd(capture_pass);
+    }
+  }
+
   WGPUSurfaceTexture st = {};
   WGPUTextureView final_view = nullptr;
 
@@ -340,39 +379,6 @@ void MainSequence::render_frame(float global_time, float beat, float peak,
       PostProcessEffect* pp =
           (PostProcessEffect*)(post_effects[i]->effect.get());
 
-      // Capture framebuffer if effect needs it
-      if (pp->needs_framebuffer_capture()) {
-        WGPUTextureView captured_view = get_auxiliary_view("captured_frame");
-        if (captured_view) {
-          // Get source texture from current_input view
-          // Note: This is a simplified blit using a render pass
-          WGPURenderPassColorAttachment capture_attachment = {};
-          capture_attachment.view = captured_view;
-          capture_attachment.resolveTarget = nullptr;
-          capture_attachment.loadOp = WGPULoadOp_Clear;
-          capture_attachment.storeOp = WGPUStoreOp_Store;
-          capture_attachment.clearValue = {0.0f, 0.0f, 0.0f, 1.0f};
-#if !defined(DEMO_CROSS_COMPILE_WIN32)
-          capture_attachment.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
-#endif
-          WGPURenderPassDescriptor capture_desc = {
-              .colorAttachmentCount = 1, .colorAttachments = &capture_attachment};
-          WGPURenderPassEncoder capture_pass =
-              wgpuCommandEncoderBeginRenderPass(encoder, &capture_desc);
-          wgpuRenderPassEncoderSetViewport(capture_pass, 0.0f, 0.0f,
-                                           (float)width_, (float)height_, 0.0f,
-                                           1.0f);
-
-          // Use passthrough effect to copy framebuffer_a (scene) to captured_frame
-          PostProcessEffect* passthrough =
-              (PostProcessEffect*)passthrough_effect_.get();
-          passthrough->update_bind_group(framebuffer_view_a_);
-          passthrough->render(capture_pass, 0, 0, 0, aspect_ratio);
-
-          wgpuRenderPassEncoderEnd(capture_pass);
-        }
-      }
-
       pp->update_bind_group(current_input);
 
       WGPURenderPassColorAttachment pp_attachment = {};
diff --git a/src/gpu/effects/cnn_effect.cc b/src/gpu/effects/cnn_effect.cc
index cb00455..7107bea 100644
--- a/src/gpu/effects/cnn_effect.cc
+++ b/src/gpu/effects/cnn_effect.cc
@@ -104,7 +104,10 @@ void CNNEffect::init(MainSequence* demo) {
 
 void CNNEffect::render(WGPURenderPassEncoder pass, float time, float beat,
                       float intensity, float aspect_ratio) {
-  if (!bind_group_) return;
+  if (!bind_group_) {
+    fprintf(stderr, "CNN render: no bind_group\n");
+    return;
+  }
 
   wgpuRenderPassEncoderSetPipeline(pass, pipeline_);
   wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_, 0, nullptr);
@@ -114,6 +117,16 @@ void CNNEffect::render(WGPURenderPassEncoder pass, float time, float beat,
 void CNNEffect::update_bind_group(WGPUTextureView input_view) {
   input_view_ = input_view;
 
+  // Update common uniforms (CRITICAL for UV calculation!)
+  const CommonPostProcessUniforms u = {
+      .resolution = {(float)width_, (float)height_},
+      .aspect_ratio = (float)width_ / (float)height_,
+      .time = 0.0f,
+      .beat = 0.0f,
+      .audio_intensity = 0.0f,
+  };
+  uniforms_.update(ctx_.queue, u);
+
   // All layers: get captured frame (original input from layer 0)
   if (demo_) {
     original_view_ = demo_->get_auxiliary_view("captured_frame");
diff --git a/workspaces/main/shaders/cnn/cnn_layer.wgsl b/workspaces/main/shaders/cnn/cnn_layer.wgsl
index 2285ef9..5834f78 100644
--- a/workspaces/main/shaders/cnn/cnn_layer.wgsl
+++ b/workspaces/main/shaders/cnn/cnn_layer.wgsl
@@ -52,6 +52,5 @@ struct CNNLayerParams {
         result = input;
     }
 
-    // Blend with ORIGINAL input from layer 0
     return mix(original, result, params.blend_amount);
 }