feat(effects): add Scratch post-process effect with reusable scratch_lines snippet

- src/shaders/render/scratch_lines.wgsl: reusable WGSL snippet registered as
  "render/scratch_lines"; call scratch_lines(uv, resolution, time)->f32 from
  any effect. Uses hash_1f from math/noise; 8 lines/frame, ~24fps flicker.
- src/effects/scratch.{wgsl,h,cc}: thin Scratch effect wrapping the snippet.
- Applied to "intro" and "rotating_cube" sequences as the final step.
- 35/35 tests passing.

handoff(Gemini): Scratch effect added. render/scratch_lines snippet is reusable.

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

8 files changed, 121 insertions, 0 deletions

diff --git a/src/effects/scratch.wgsl b/src/effects/scratch.wgsl
new file mode 100644
index 0000000..818202e
--- /dev/null
+++ b/src/effects/scratch.wgsl
@@ -0,0 +1,14 @@
+// Scratch effect - overlays film scratch lines on top of the input buffer
+#include "sequence_uniforms"
+#include "render/fullscreen_uv_vs"
+#include "render/scratch_lines"
+
+@group(0) @binding(0) var input_sampler: sampler;
+@group(0) @binding(1) var input_texture: texture_2d<f32>;
+@group(0) @binding(2) var<uniform> uniforms: UniformsSequenceParams;
+
+@fragment fn fs_main(in: VertexOutput) -> @location(0) vec4f {
+    let color = textureSample(input_texture, input_sampler, in.uv);
+    let s = scratch_lines(in.uv, uniforms.resolution, uniforms.time);
+    return vec4f(color.rgb + vec3f(s), color.a);
+}
diff --git a/src/effects/scratch_effect.cc b/src/effects/scratch_effect.cc
new file mode 100644
index 0000000..f49e601
--- /dev/null
+++ b/src/effects/scratch_effect.cc
@@ -0,0 +1,44 @@
+// Scratch effect - film scratch overlay post-process
+
+#include "effects/scratch_effect.h"
+#include "effects/shaders.h"
+#include "gpu/post_process_helper.h"
+#include "util/fatal_error.h"
+
+Scratch::Scratch(const GpuContext& ctx, const std::vector<std::string>& inputs,
+                 const std::vector<std::string>& outputs, float start_time,
+                 float end_time)
+    : Effect(ctx, inputs, outputs, start_time, end_time) {
+  HEADLESS_RETURN_IF_NULL(ctx_.device);
+
+  create_linear_sampler();
+
+  pipeline_.set(create_post_process_pipeline(ctx_.device,
+                                             WGPUTextureFormat_RGBA8Unorm,
+                                             scratch_shader_wgsl));
+}
+
+void Scratch::render(WGPUCommandEncoder encoder,
+                     const UniformsSequenceParams& params,
+                     NodeRegistry& nodes) {
+  WGPUTextureView input_view = nodes.get_view(input_nodes_[0]);
+  WGPUTextureView output_view = nodes.get_view(output_nodes_[0]);
+
+  pp_update_bind_group(ctx_.device, pipeline_.get(), bind_group_.get_address(),
+                       input_view, uniforms_buffer_.get(), {nullptr, 0});
+
+  WGPURenderPassColorAttachment color_attachment = {};
+  gpu_init_color_attachment(color_attachment, output_view);
+
+  WGPURenderPassDescriptor pass_desc = {};
+  pass_desc.colorAttachmentCount = 1;
+  pass_desc.colorAttachments = &color_attachment;
+
+  WGPURenderPassEncoder pass =
+      wgpuCommandEncoderBeginRenderPass(encoder, &pass_desc);
+  wgpuRenderPassEncoderSetPipeline(pass, pipeline_.get());
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_.get(), 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
+  wgpuRenderPassEncoderEnd(pass);
+  wgpuRenderPassEncoderRelease(pass);
+}
diff --git a/src/effects/scratch_effect.h b/src/effects/scratch_effect.h
new file mode 100644
index 0000000..fb36a96
--- /dev/null
+++ b/src/effects/scratch_effect.h
@@ -0,0 +1,20 @@
+// Scratch effect - film scratch overlay post-process
+// Reads input buffer, additively blends scratch_lines() on top.
+
+#pragma once
+#include "gpu/effect.h"
+#include "gpu/wgpu_resource.h"
+
+class Scratch : public Effect {
+ public:
+  Scratch(const GpuContext& ctx, const std::vector<std::string>& inputs,
+          const std::vector<std::string>& outputs, float start_time,
+          float end_time);
+
+  void render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params,
+              NodeRegistry& nodes) override;
+
+ private:
+  RenderPipeline pipeline_;
+  BindGroup bind_group_;
+};
diff --git a/src/effects/shaders.cc b/src/effects/shaders.cc
index c6a81d0..e4b9b25 100644
--- a/src/effects/shaders.cc
+++ b/src/effects/shaders.cc
@@ -51,6 +51,8 @@ void InitShaderComposer() {
   register_if_exists("ray_box", AssetId::ASSET_SHADER_RAY_BOX);
   register_if_exists("ray_triangle", AssetId::ASSET_SHADER_RAY_TRIANGLE);
 
+  register_if_exists("render/scratch_lines",
+                     AssetId::ASSET_SHADER_RENDER_SCRATCH_LINES);
   register_if_exists("render/fullscreen_vs",
                      AssetId::ASSET_SHADER_RENDER_FULLSCREEN_VS);
   register_if_exists("render/fullscreen_uv_vs",
@@ -97,6 +99,7 @@ const char* rotating_cube_wgsl =
 const char* flash_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_FLASH);
 const char* scene1_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCENE1);
 const char* scene2_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCENE2);
+const char* scratch_shader_wgsl = SafeGetAsset(AssetId::ASSET_SHADER_SCRATCH);
 
 // Compute shaders
 const char* gen_noise_compute_wgsl =
diff --git a/src/effects/shaders.h b/src/effects/shaders.h
index 5fc442a..76b5d96 100644
--- a/src/effects/shaders.h
+++ b/src/effects/shaders.h
@@ -16,6 +16,7 @@ extern const char* rotating_cube_wgsl;
 extern const char* flash_shader_wgsl;
 extern const char* scene1_shader_wgsl;
 extern const char* scene2_shader_wgsl;
+extern const char* scratch_shader_wgsl;
 
 // Compute shaders
 extern const char* gen_noise_compute_wgsl;
diff --git a/src/gpu/demo_effects.h b/src/gpu/demo_effects.h
index e1a9c17..ecc37df 100644
--- a/src/gpu/demo_effects.h
+++ b/src/gpu/demo_effects.h
@@ -28,6 +28,7 @@
 #include "effects/rotating_cube_effect.h"
 #include "effects/scene1_effect.h"
 #include "effects/scene2_effect.h"
+#include "effects/scratch_effect.h"
 
 // TODO: Port CNN effects
 // #include "../../cnn_v1/src/cnn_v1_effect.h"
diff --git a/src/shaders/render/scratch_lines.wgsl b/src/shaders/render/scratch_lines.wgsl
new file mode 100644
index 0000000..04ed6f8
--- /dev/null
+++ b/src/shaders/render/scratch_lines.wgsl
@@ -0,0 +1,35 @@
+// Horizontal film scratch lines utility
+// Returns scratch intensity [0,1] to additively overlay on a color buffer.
+//
+// Parameters:
+//   uv         - normalized texture coordinates [0,1]
+//   resolution - screen size in pixels (used for sub-pixel thickness)
+//   time       - physical time in seconds
+//
+// Simulates aged/damaged film: ~8 random horizontal lines per frame,
+// each with independent position, thickness, brightness and on/off state.
+// Time is quantized to 24 buckets/sec so scratches flicker like film frames.
+#include "math/noise"
+
+fn scratch_lines(uv: vec2f, resolution: vec2f, time: f32) -> f32 {
+    // Quantize to ~24fps to simulate film frame rate
+    let t = floor(time * 24.0);
+
+    var intensity = 0.0;
+    for (var i = 0; i < 8; i++) {
+        let seed = f32(i) * 17.3 + t;
+        // ~25% chance this scratch is visible this frame
+        let visible = step(0.75, hash_1f(seed + 3.1));
+        // Random vertical position [0, 1]
+        let y = hash_1f(seed + 7.9);
+        // Thickness in pixels [1, 4]
+        let thickness = hash_1f(seed + 13.5) * 3.0 + 1.0;
+        // Brightness [0.5, 1.0]
+        let brightness = hash_1f(seed + 21.7) * 0.5 + 0.5;
+        // Soft linear falloff from line center
+        let dy = abs(uv.y - y) * resolution.y;
+        let line = clamp(1.0 - dy / thickness, 0.0, 1.0);
+        intensity += line * brightness * visible;
+    }
+    return clamp(intensity, 0.0, 1.0);
+}
diff --git a/src/tests/gpu/test_demo_effects.cc b/src/tests/gpu/test_demo_effects.cc
index 5c4bffc..3aa6230 100644
--- a/src/tests/gpu/test_demo_effects.cc
+++ b/src/tests/gpu/test_demo_effects.cc
@@ -70,6 +70,9 @@ static void test_effects() {
       {"Scene2", std::make_shared<Scene2Effect>(
                      fixture.ctx(), std::vector<std::string>{"source"},
                      std::vector<std::string>{"sink"}, 0.0f, 1000.0f)},
+      {"Scratch", std::make_shared<Scratch>(
+                      fixture.ctx(), std::vector<std::string>{"source"},
+                      std::vector<std::string>{"sink"}, 0.0f, 1000.0f)},
   };
 
   int passed = 0;