feat(gpu): add SDF camera infrastructure and effect base class

Add unified camera system for SDF raymarching effects:
- CameraParams struct (80 bytes): inv_view matrix + FOV/near/far/aspect
- SDFEffect base class: manages camera uniform, provides update_camera() helpers
- camera_common.wgsl: getCameraRay(), position/forward/up/right extractors
- SDFTestEffect: working example with orbiting camera + animated sphere

Refactor effect headers:
- Extract class definitions from demo_effects.h to individual .h files
- Update includes in .cc files to use specific headers
- Cleaner compilation dependencies, faster incremental builds

Documentation:
- Add SDF_EFFECT_GUIDE.md with complete workflow
- Update ARCHITECTURE.md, UNIFORM_BUFFER_GUIDELINES.md
- Update EFFECT_WORKFLOW.md, CONTRIBUTING.md

Tests: 34/34 passing, SDFTestEffect validated

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

23 files changed, 304 insertions, 10 deletions

diff --git a/src/effects/chroma_aberration_effect.cc b/src/effects/chroma_aberration_effect.cc
index 2a92225..4038696 100644
--- a/src/effects/chroma_aberration_effect.cc
+++ b/src/effects/chroma_aberration_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the ChromaAberrationEffect with parameterization.
 
-#include "gpu/demo_effects.h"
+#include "effects/chroma_aberration_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 
 // --- ChromaAberrationEffect ---
 
diff --git a/src/effects/chroma_aberration_effect.h b/src/effects/chroma_aberration_effect.h
new file mode 100644
index 0000000..1790952
--- /dev/null
+++ b/src/effects/chroma_aberration_effect.h
@@ -0,0 +1,29 @@
+// This file is part of the 64k demo project.
+// It declares the ChromaAberrationEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "gpu/uniform_helper.h"
+
+// Parameters for ChromaAberrationEffect (set at construction time)
+struct ChromaAberrationParams {
+  float offset_scale = 0.02f; // Default: 2% screen offset
+  float angle = 0.0f;         // Default: horizontal (0 radians)
+};
+
+class ChromaAberrationEffect : public PostProcessEffect {
+ public:
+  // Backward compatibility constructor (uses default params)
+  ChromaAberrationEffect(const GpuContext& ctx);
+  // New parameterized constructor
+  ChromaAberrationEffect(const GpuContext& ctx,
+                         const ChromaAberrationParams& params);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+  ChromaAberrationParams params_;
+  UniformBuffer<ChromaAberrationParams> params_buffer_;
+};
diff --git a/src/effects/distort_effect.cc b/src/effects/distort_effect.cc
index f4e68d2..aa72386 100644
--- a/src/effects/distort_effect.cc
+++ b/src/effects/distort_effect.cc
@@ -1,8 +1,9 @@
 // This file is part of the 64k demo project.
 // It implements the DistortEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/distort_effect.h"
 #include "gpu/gpu.h"
+#include "gpu/shaders.h"
 
 // --- DistortEffect ---
 DistortEffect::DistortEffect(const GpuContext& ctx)
diff --git a/src/effects/distort_effect.h b/src/effects/distort_effect.h
new file mode 100644
index 0000000..548cf91
--- /dev/null
+++ b/src/effects/distort_effect.h
@@ -0,0 +1,28 @@
+// This file is part of the 64k demo project.
+// It declares the DistortEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "gpu/uniform_helper.h"
+
+// Parameters for DistortEffect
+struct DistortParams {
+  float strength = 0.01f; // Default distortion strength
+  float speed = 1.0f;     // Default distortion speed
+};
+static_assert(sizeof(DistortParams) == 8,
+              "DistortParams must be 8 bytes for WGSL alignment");
+
+class DistortEffect : public PostProcessEffect {
+ public:
+  DistortEffect(const GpuContext& ctx);
+  DistortEffect(const GpuContext& ctx, const DistortParams& params);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+  DistortParams params_;
+  UniformBuffer<DistortParams> params_buffer_;
+};
diff --git a/src/effects/gaussian_blur_effect.cc b/src/effects/gaussian_blur_effect.cc
index 6a0675d..b5961fa 100644
--- a/src/effects/gaussian_blur_effect.cc
+++ b/src/effects/gaussian_blur_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the GaussianBlurEffect with parameterization.
 
-#include "gpu/demo_effects.h"
+#include "effects/gaussian_blur_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 
 // --- GaussianBlurEffect ---
 
diff --git a/src/effects/gaussian_blur_effect.h b/src/effects/gaussian_blur_effect.h
new file mode 100644
index 0000000..651c5c3
--- /dev/null
+++ b/src/effects/gaussian_blur_effect.h
@@ -0,0 +1,32 @@
+// This file is part of the 64k demo project.
+// It declares the GaussianBlurEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "gpu/uniform_helper.h"
+
+// Parameters for GaussianBlurEffect (set at construction time)
+struct GaussianBlurParams {
+  float strength = 1.0f; // Default
+  float strength_audio = 0.5f; // how much to pulse with audio
+  float stretch = 1.f;   // y/x axis ratio
+  float _pad = 0.;
+};
+static_assert(sizeof(GaussianBlurParams) == 16,
+              "GaussianBlurParams must be 16 bytes for WGSL alignment");
+
+class GaussianBlurEffect : public PostProcessEffect {
+ public:
+  // Backward compatibility constructor (uses default params)
+  GaussianBlurEffect(const GpuContext& ctx);
+  // New parameterized constructor
+  GaussianBlurEffect(const GpuContext& ctx, const GaussianBlurParams& params);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+  GaussianBlurParams params_;
+  UniformBuffer<GaussianBlurParams> params_buffer_;
+};
diff --git a/src/effects/heptagon_effect.cc b/src/effects/heptagon_effect.cc
index 273adc2..d15882d 100644
--- a/src/effects/heptagon_effect.cc
+++ b/src/effects/heptagon_effect.cc
@@ -1,8 +1,9 @@
 // This file is part of the 64k demo project.
 // It implements the HeptagonEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/heptagon_effect.h"
 #include "gpu/gpu.h"
+#include "gpu/shaders.h"
 #include "util/mini_math.h"
 
 // --- HeptagonEffect ---
diff --git a/src/effects/heptagon_effect.h b/src/effects/heptagon_effect.h
new file mode 100644
index 0000000..fe19839
--- /dev/null
+++ b/src/effects/heptagon_effect.h
@@ -0,0 +1,16 @@
+// This file is part of the 64k demo project.
+// It declares the HeptagonEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+
+class HeptagonEffect : public Effect {
+ public:
+  HeptagonEffect(const GpuContext& ctx);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+
+ private:
+  RenderPass pass_;
+};
diff --git a/src/effects/moving_ellipse_effect.cc b/src/effects/moving_ellipse_effect.cc
index e641927..6fb0195 100644
--- a/src/effects/moving_ellipse_effect.cc
+++ b/src/effects/moving_ellipse_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the MovingEllipseEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/moving_ellipse_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 
 // --- MovingEllipseEffect ---
 MovingEllipseEffect::MovingEllipseEffect(const GpuContext& ctx) : Effect(ctx) {
diff --git a/src/effects/moving_ellipse_effect.h b/src/effects/moving_ellipse_effect.h
new file mode 100644
index 0000000..46c1f0e
--- /dev/null
+++ b/src/effects/moving_ellipse_effect.h
@@ -0,0 +1,16 @@
+// This file is part of the 64k demo project.
+// It declares the MovingEllipseEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+
+class MovingEllipseEffect : public Effect {
+ public:
+  MovingEllipseEffect(const GpuContext& ctx);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+
+ private:
+  RenderPass pass_;
+};
diff --git a/src/effects/particle_defs.h b/src/effects/particle_defs.h
new file mode 100644
index 0000000..dcbb830
--- /dev/null
+++ b/src/effects/particle_defs.h
@@ -0,0 +1,13 @@
+// This file is part of the 64k demo project.
+// It defines common structures for particle-based effects.
+
+#pragma once
+
+static const int NUM_PARTICLES = 10000;
+
+struct Particle {
+  float pos[4];
+  float vel[4];
+  float rot[4];
+  float color[4];
+};
diff --git a/src/effects/particle_spray_effect.cc b/src/effects/particle_spray_effect.cc
index 0b0dba1..1acf67d 100644
--- a/src/effects/particle_spray_effect.cc
+++ b/src/effects/particle_spray_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the ParticleSprayEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/particle_spray_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 #include <vector>
 
 // --- ParticleSprayEffect ---
diff --git a/src/effects/particle_spray_effect.h b/src/effects/particle_spray_effect.h
new file mode 100644
index 0000000..c83d691
--- /dev/null
+++ b/src/effects/particle_spray_effect.h
@@ -0,0 +1,21 @@
+// This file is part of the 64k demo project.
+// It declares the ParticleSprayEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "effects/particle_defs.h"
+
+class ParticleSprayEffect : public Effect {
+ public:
+  ParticleSprayEffect(const GpuContext& ctx);
+  void compute(WGPUCommandEncoder encoder,
+               const CommonPostProcessUniforms& uniforms) override;
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+
+ private:
+  ComputePass compute_pass_;
+  RenderPass render_pass_;
+  GpuBuffer particles_buffer_;
+};
diff --git a/src/effects/particles_effect.cc b/src/effects/particles_effect.cc
index b05aecd..25589fd 100644
--- a/src/effects/particles_effect.cc
+++ b/src/effects/particles_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the ParticlesEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/particles_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 #include <vector>
 
 // --- ParticlesEffect ---
diff --git a/src/effects/particles_effect.h b/src/effects/particles_effect.h
new file mode 100644
index 0000000..6d46ea2
--- /dev/null
+++ b/src/effects/particles_effect.h
@@ -0,0 +1,21 @@
+// This file is part of the 64k demo project.
+// It declares the ParticlesEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "effects/particle_defs.h"
+
+class ParticlesEffect : public Effect {
+ public:
+  ParticlesEffect(const GpuContext& ctx);
+  void compute(WGPUCommandEncoder encoder,
+               const CommonPostProcessUniforms& uniforms) override;
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+
+ private:
+  ComputePass compute_pass_;
+  RenderPass render_pass_;
+  GpuBuffer particles_buffer_;
+};
diff --git a/src/effects/passthrough_effect.cc b/src/effects/passthrough_effect.cc
index aedb387..50f5a5c 100644
--- a/src/effects/passthrough_effect.cc
+++ b/src/effects/passthrough_effect.cc
@@ -1,8 +1,9 @@
 // This file is part of the 64k demo project.
 // It implements the PassthroughEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/passthrough_effect.h"
 #include "gpu/gpu.h"
+#include "gpu/shaders.h"
 
 // --- PassthroughEffect ---
 PassthroughEffect::PassthroughEffect(const GpuContext& ctx)
diff --git a/src/effects/passthrough_effect.h b/src/effects/passthrough_effect.h
new file mode 100644
index 0000000..36f93f2
--- /dev/null
+++ b/src/effects/passthrough_effect.h
@@ -0,0 +1,14 @@
+// This file is part of the 64k demo project.
+// It declares the PassthroughEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+
+class PassthroughEffect : public PostProcessEffect {
+ public:
+  PassthroughEffect(const GpuContext& ctx);
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+};
diff --git a/src/effects/sdf_test_effect.cc b/src/effects/sdf_test_effect.cc
new file mode 100644
index 0000000..28b3513
--- /dev/null
+++ b/src/effects/sdf_test_effect.cc
@@ -0,0 +1,36 @@
+// This file is part of the 64k demo project.
+// It implements the SDFTestEffect.
+
+#include "effects/sdf_test_effect.h"
+#include "gpu/gpu.h"
+#include "gpu/shaders.h"
+
+SDFTestEffect::SDFTestEffect(const GpuContext& ctx) : SDFEffect(ctx) {
+  ResourceBinding bindings[] = {
+      {uniforms_.get(), WGPUBufferBindingType_Uniform},
+      {camera_params_.get(), WGPUBufferBindingType_Uniform}};
+  pass_ = gpu_create_render_pass(ctx_.device, ctx_.format,
+                                  sdf_test_shader_wgsl, bindings, 2);
+  pass_.vertex_count = 3;
+}
+
+void SDFTestEffect::render(WGPURenderPassEncoder pass,
+                           const CommonPostProcessUniforms& uniforms) {
+  // Update common uniforms
+  uniforms_.update(ctx_.queue, uniforms);
+
+  // Update camera (simple orbiting camera)
+  const float radius = 5.0f;
+  const float speed = 0.3f;
+  vec3 cam_pos(std::cos(uniforms.time * speed) * radius, 2.0f,
+               std::sin(uniforms.time * speed) * radius);
+  vec3 cam_target(0.0f, 0.0f, 0.0f);
+  vec3 cam_up(0.0f, 1.0f, 0.0f);
+  update_camera(cam_pos, cam_target, cam_up, 0.785398f, 0.1f, 100.0f,
+                uniforms.aspect_ratio);
+
+  // Render
+  wgpuRenderPassEncoderSetPipeline(pass, pass_.pipeline);
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, pass_.bind_group, 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, pass_.vertex_count, 1, 0, 0);
+}
diff --git a/src/effects/sdf_test_effect.h b/src/effects/sdf_test_effect.h
new file mode 100644
index 0000000..41baf83
--- /dev/null
+++ b/src/effects/sdf_test_effect.h
@@ -0,0 +1,16 @@
+// This file is part of the 64k demo project.
+// It demonstrates SDFEffect base class usage.
+
+#pragma once
+
+#include "gpu/sdf_effect.h"
+
+class SDFTestEffect : public SDFEffect {
+ public:
+  SDFTestEffect(const GpuContext& ctx);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+
+ private:
+  RenderPass pass_;
+};
diff --git a/src/effects/solarize_effect.cc b/src/effects/solarize_effect.cc
index cdb9354..a367e51 100644
--- a/src/effects/solarize_effect.cc
+++ b/src/effects/solarize_effect.cc
@@ -1,8 +1,9 @@
 // This file is part of the 64k demo project.
 // It implements the SolarizeEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/solarize_effect.h"
 #include "gpu/gpu.h"
+#include "gpu/shaders.h"
 
 // --- SolarizeEffect ---
 SolarizeEffect::SolarizeEffect(const GpuContext& ctx) : PostProcessEffect(ctx) {
diff --git a/src/effects/solarize_effect.h b/src/effects/solarize_effect.h
new file mode 100644
index 0000000..6132f58
--- /dev/null
+++ b/src/effects/solarize_effect.h
@@ -0,0 +1,16 @@
+// This file is part of the 64k demo project.
+// It declares the SolarizeEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+
+class SolarizeEffect : public PostProcessEffect {
+ public:
+  SolarizeEffect(const GpuContext& ctx);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+};
diff --git a/src/effects/vignette_effect.cc b/src/effects/vignette_effect.cc
index f5c3f05..3ddbee3 100644
--- a/src/effects/vignette_effect.cc
+++ b/src/effects/vignette_effect.cc
@@ -1,9 +1,10 @@
 // This file is part of the 64k demo project.
 // It implements the VignetteEffect.
 
-#include "gpu/demo_effects.h"
+#include "effects/vignette_effect.h"
 #include "gpu/gpu.h"
 #include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
 
 VignetteEffect::VignetteEffect(const GpuContext& ctx)
     : VignetteEffect(ctx, VignetteParams()) {
diff --git a/src/effects/vignette_effect.h b/src/effects/vignette_effect.h
new file mode 100644
index 0000000..f891d14
--- /dev/null
+++ b/src/effects/vignette_effect.h
@@ -0,0 +1,26 @@
+// This file is part of the 64k demo project.
+// It declares the VignetteEffect.
+
+#pragma once
+
+#include "gpu/effect.h"
+#include "gpu/uniform_helper.h"
+
+// Parameters for VignetteEffect
+struct VignetteParams {
+  float radius = 0.5f;   // Radius of the clear center
+  float softness = 0.5f; // Softness of the vignette edge
+};
+
+class VignetteEffect : public PostProcessEffect {
+ public:
+  VignetteEffect(const GpuContext& ctx);
+  VignetteEffect(const GpuContext& ctx, const VignetteParams& params);
+  void render(WGPURenderPassEncoder pass,
+              const CommonPostProcessUniforms& uniforms) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+  VignetteParams params_;
+  UniformBuffer<VignetteParams> params_buffer_;
+};