refactor(gpu): Relocate effects to src/effects and streamline includes

This refactoring improves the project's structure by decoupling visual effects from the core GPU module. All effect implementations have been moved from  to a new top-level  directory. Shared utilities like , , and  have been consolidated into the parent  directory.

- **Motivation**: To create a clearer separation of concerns, making the codebase easier to navigate and maintain. This move treats effects as a distinct layer that depends on the core GPU module, rather than being embedded within it.

- **Changes**:
  - Created new  directory.
  - Moved all effect source files (, ) to .
  - Moved shared helpers (, , ) to .
  - Updated  and  to reflect the new file locations for all build targets.
  - Corrected all  directives across the entire codebase (, , ) to point to the new paths.
  - Updated all markdown documentation ( files) to ensure file paths and architectural descriptions are accurate.
  - Fixed several compiler errors related to incorrect enum casting () that were exposed during cross-compilation for Windows.

- **Verification**:
  - The entire project builds successfully for both native and Windows cross-compilation targets.
  - All 34 tests pass (Usage

  ctest [options]).
  - The --- Running Native Build & Tests ---
Configuring with all options enabled (tests + tools)...
--
-- Build Configuration:
--   DEMO_SIZE_OPT:           ON
--   DEMO_STRIP_ALL:          ON
--   DEMO_FINAL_STRIP:        OFF
--   DEMO_STRIP_EXTERNAL_LIBS: OFF
--   DEMO_BUILD_TESTS:        ON
--   DEMO_BUILD_TOOLS:        ON
--   DEMO_ENABLE_COVERAGE:    OFF
--   DEMO_ENABLE_DEBUG_LOGS:  OFF
--   DEMO_HEADLESS:           OFF
--   DEMO_WORKSPACE:          main
--
-- Loaded workspace: Main Demo
--   Timeline: timeline.seq
--   Music: pop_punk_drums.track
--   Assets: assets.txt
-- Using workspace: main
-- Configuring done (0.0s)
-- Generating done (0.1s)
-- Build files have been written to: /Users/skal/demo/build
Building all targets (demo, tests, and tools)...
[  0%] Built target validate_uniforms_script
[  1%] Built target procedural
[  2%] Validating uniform buffer sizes and alignments...
[  3%] Built target tracker_compiler
[  4%] Built target test_3d
[  4%] Built target test_maths
[  4%] Built target seq_compiler
[  4%] Built target tracker_compiler_host
[  5%] Built target asset_packer
[  5%] Built target test_procedural
[  6%] Compiling demo sequence from workspace main...
[  6%] Built target generate_tracker_music
[  6%] Built target generate_test_demo_music
[  6%] Compiling test_demo sequence...
Using BPM: 90
Successfully generated timeline with 16 sequences.
Using BPM: 120
Demo end time: 16.000000s
Successfully generated timeline with 1 sequences.
[  6%] Built target generate_test_demo_timeline
[  6%] Built target generate_timeline
Validation Warning for 'CommonPostProcessUniforms': Matching WGSL struct not found.
Validation OK for 'FadeParams': Size 16 matches C++ expected size.
Validation OK for 'ThemeModulationParams': Size 16 matches C++ expected size.
Validation OK for 'GaussianBlurParams': Size 8 matches C++ expected size.
Validation OK for 'DistortParams': Size 8 matches C++ expected size.
Validation OK for 'CircleMaskParams': Size 16 matches C++ expected size.
[  6%] Built target generate_test_assets
[  7%] Built target generate_demo_assets
[  7%] Built target validate_uniforms
[  8%] Built target util
[ 10%] Built target test_assets
[ 11%] Built target test_shader_assets
[ 12%] Built target test_file_watcher
[ 15%] Built target 3d
[ 21%] Built target test_platform
[ 22%] Built target audio
[ 23%] Built target test_window
[ 26%] Built target test_fft
[ 27%] Built target test_synth
[ 27%] Built target test_spectral_brush
[ 27%] Built target test_physics
[ 28%] Built target test_dct
[ 31%] Building CXX object CMakeFiles/gpu.dir/src/gpu/effect.cc.o
[ 30%] Built target test_mock_backend
[ 32%] Built target test_scene_loader
[ 33%] Built target test_audio_backend
[ 34%] Built target test_audio_gen
[ 36%] Built target test_silent_backend
[ 39%] Built target test_jittered_audio
[ 39%] Building CXX object CMakeFiles/gpu.dir/src/effects/heptagon_effect.cc.o
[ 42%] Built target test_wav_dump
[ 44%] Built target test_tracker_timing
[ 44%] Building CXX object CMakeFiles/gpu.dir/src/effects/particles_effect.cc.o
[ 45%] Building CXX object CMakeFiles/gpu.dir/src/effects/passthrough_effect.cc.o
[ 47%] Built target test_variable_tempo
[ 50%] Built target test_audio_engine
[ 52%] Built target test_tracker
[ 52%] Building CXX object CMakeFiles/gpu.dir/src/effects/moving_ellipse_effect.cc.o
[ 52%] Building CXX object CMakeFiles/gpu.dir/src/effects/particle_spray_effect.cc.o
[ 52%] Building CXX object CMakeFiles/gpu.dir/src/effects/gaussian_blur_effect.cc.o
[ 54%] Built target test_spectool
[ 55%] Building CXX object CMakeFiles/gpu.dir/src/effects/solarize_effect.cc.o
[ 55%] Building CXX object CMakeFiles/gpu.dir/src/effects/scene1_effect.cc.o
[ 55%] Building CXX object CMakeFiles/gpu.dir/src/effects/chroma_aberration_effect.cc.o
[ 55%] Building CXX object CMakeFiles/gpu.dir/src/gpu/shaders.cc.o
[ 57%] Building CXX object CMakeFiles/gpu.dir/src/effects/vignette_effect.cc.o
[ 57%] Building CXX object CMakeFiles/gpu.dir/src/gpu/post_process_helper.cc.o
[ 57%] Linking CXX static library libgpu.a
[ 60%] Built target gpu
[ 60%] Linking CXX executable test_uniform_helper
[ 60%] Linking CXX executable test_shader_composer
[ 60%] Building CXX object CMakeFiles/test_sequence.dir/src/tests/assets/test_sequence.cc.o
[ 61%] Linking CXX executable test_noise_functions
[ 62%] Linking CXX executable test_shader_compilation
[ 62%] Building CXX object CMakeFiles/test_demo.dir/src/app/test_demo.cc.o
[ 62%] Building CXX object CMakeFiles/demo64k.dir/src/app/main.cc.o
[ 62%] Building CXX object CMakeFiles/test_3d_render.dir/src/generated/timeline.cc.o
[ 63%] Built target test_uniform_helper
[ 64%] Built target test_shader_composer
[ 64%] Building CXX object CMakeFiles/test_3d_physics.dir/src/generated/timeline.cc.o
[ 65%] Built target test_noise_functions
[ 66%] Built target test_shader_compilation
[ 67%] Building CXX object CMakeFiles/test_mesh.dir/src/generated/timeline.cc.o
[ 67%] Building CXX object CMakeFiles/test_effect_base.dir/src/tests/gpu/test_effect_base.cc.o
[ 67%] Building CXX object CMakeFiles/test_demo_effects.dir/src/tests/gpu/test_demo_effects.cc.o
[ 67%] Building CXX object CMakeFiles/test_sequence.dir/src/generated/timeline.cc.o
[ 68%] Building CXX object CMakeFiles/test_demo.dir/src/generated/test_demo_timeline.cc.o
[ 68%] Building CXX object CMakeFiles/demo64k.dir/src/generated/timeline.cc.o
[ 68%] Linking CXX executable test_3d_render
[ 68%] Building CXX object CMakeFiles/test_effect_base.dir/src/generated/timeline.cc.o
[ 68%] Linking CXX executable test_3d_physics
[ 68%] Linking CXX executable test_mesh
[ 71%] Built target test_3d_render
[ 71%] Building CXX object CMakeFiles/test_post_process_helper.dir/src/tests/gpu/test_post_process_helper.cc.o
[ 72%] Building CXX object CMakeFiles/test_demo_effects.dir/src/generated/timeline.cc.o
[ 72%] Linking CXX executable test_demo
[ 75%] Built target test_3d_physics
[ 77%] Built target test_mesh
[ 77%] Linking CXX executable test_texture_manager
[ 78%] Linking CXX executable test_sequence
[ 78%] Linking CXX executable test_gpu_procedural
[ 80%] Built target test_demo
[ 81%] Linking CXX executable test_gpu_composite
[ 81%] Linking CXX executable demo64k
[ 83%] Built target test_sequence
[ 85%] Built target test_texture_manager
[ 86%] Built target test_gpu_procedural
[ 86%] Linking CXX executable test_post_process_helper
[ 86%] Linking CXX executable test_effect_base
[ 87%] Built target test_gpu_composite
[ 90%] Built target demo64k
[ 92%] Built target test_post_process_helper
[ 96%] Built target test_effect_base
[ 96%] Linking CXX executable test_demo_effects
[100%] Built target test_demo_effects
Running test suite...
Test project /Users/skal/demo/build
      Start  1: HammingWindowTest
 1/34 Test  #1: HammingWindowTest ................   Passed    0.00 sec
      Start  2: MathUtilsTest
 2/34 Test  #2: MathUtilsTest ....................   Passed    0.00 sec
      Start  3: FileWatcherTest
 3/34 Test  #3: FileWatcherTest ..................   Passed    0.00 sec
      Start  4: SynthEngineTest
 4/34 Test  #4: SynthEngineTest ..................   Passed    0.00 sec
      Start  5: DctTest
 5/34 Test  #5: DctTest ..........................   Passed    0.00 sec
      Start  6: FftTest
 6/34 Test  #6: FftTest ..........................   Passed    0.01 sec
      Start  7: SpectralBrushTest
 7/34 Test  #7: SpectralBrushTest ................   Passed    0.01 sec
      Start  8: AudioGenTest
 8/34 Test  #8: AudioGenTest .....................   Passed    0.00 sec
      Start  9: AudioBackendTest
 9/34 Test  #9: AudioBackendTest .................   Passed    0.00 sec
      Start 10: SilentBackendTest
10/34 Test #10: SilentBackendTest ................   Passed    0.00 sec
      Start 11: MockAudioBackendTest
11/34 Test #11: MockAudioBackendTest .............   Passed    0.00 sec
      Start 12: WavDumpBackendTest
12/34 Test #12: WavDumpBackendTest ...............   Passed    0.00 sec
      Start 13: JitteredAudioBackendTest
13/34 Test #13: JitteredAudioBackendTest .........   Passed    0.00 sec
      Start 14: TrackerTimingTest
14/34 Test #14: TrackerTimingTest ................   Passed    0.00 sec
      Start 15: VariableTempoTest
15/34 Test #15: VariableTempoTest ................   Passed    0.00 sec
      Start 16: TrackerSystemTest
16/34 Test #16: TrackerSystemTest ................   Passed    0.01 sec
      Start 17: AudioEngineTest
17/34 Test #17: AudioEngineTest ..................   Passed    0.00 sec
      Start 18: ShaderAssetValidation
18/34 Test #18: ShaderAssetValidation ............   Passed    0.00 sec
      Start 19: ShaderCompilationTest
19/34 Test #19: ShaderCompilationTest ............   Passed    0.02 sec
      Start 20: NoiseFunctionsTest
20/34 Test #20: NoiseFunctionsTest ...............   Passed    0.01 sec
      Start 21: UniformHelperTest
21/34 Test #21: UniformHelperTest ................   Passed    0.00 sec
      Start 22: AssetManagerTest
22/34 Test #22: AssetManagerTest .................   Passed    0.01 sec
      Start 23: SequenceSystemTest
23/34 Test #23: SequenceSystemTest ...............   Passed    0.01 sec
      Start 24: ProceduralGenTest
24/34 Test #24: ProceduralGenTest ................   Passed    0.01 sec
      Start 25: PhysicsTest
25/34 Test #25: PhysicsTest ......................   Passed    0.01 sec
      Start 26: ThreeDSystemTest
26/34 Test #26: ThreeDSystemTest .................   Passed    0.00 sec
      Start 27: ShaderComposerTest
27/34 Test #27: ShaderComposerTest ...............   Passed    0.01 sec
      Start 28: SceneLoaderTest
28/34 Test #28: SceneLoaderTest ..................   Passed    0.01 sec
      Start 29: EffectBaseTest
29/34 Test #29: EffectBaseTest ...................   Passed    0.04 sec
      Start 30: DemoEffectsTest
30/34 Test #30: DemoEffectsTest ..................   Passed    0.03 sec
      Start 31: PostProcessHelperTest
31/34 Test #31: PostProcessHelperTest ............   Passed    0.02 sec
      Start 32: TextureManagerTest
32/34 Test #32: TextureManagerTest ...............   Passed    0.02 sec
      Start 33: GpuProceduralTest
33/34 Test #33: GpuProceduralTest ................   Passed    0.18 sec
      Start 34: GpuCompositeTest
34/34 Test #34: GpuCompositeTest .................   Passed    0.20 sec

100% tests passed, 0 tests failed out of 34

Label Time Summary:
3d        =   0.01 sec*proc (3 tests)
assets    =   0.02 sec*proc (2 tests)
audio     =   0.07 sec*proc (15 tests)
gpu       =   0.54 sec*proc (11 tests)
util      =   0.01 sec*proc (3 tests)

Total Test time (real) =   0.67 sec
Verifying tools compile...
[  9%] Built target procedural
[ 18%] Built target tracker_compiler_host
[ 18%] Built target tracker_compiler
[ 18%] Built target generate_tracker_music
[ 18%] Built target asset_packer
[ 27%] Built target generate_demo_assets
[ 27%] Built target generate_test_assets
[ 36%] Built target util
[ 81%] Built target audio
[100%] Built target test_spectool

--- Running Windows Cross-Compilation Build ---
Building native tools...
--
-- Build Configuration:
--   DEMO_SIZE_OPT:           OFF
--   DEMO_STRIP_ALL:          OFF
--   DEMO_FINAL_STRIP:        OFF
--   DEMO_STRIP_EXTERNAL_LIBS: OFF
--   DEMO_BUILD_TESTS:        OFF
--   DEMO_BUILD_TOOLS:        OFF
--   DEMO_ENABLE_COVERAGE:    OFF
--   DEMO_ENABLE_DEBUG_LOGS:  OFF
--   DEMO_HEADLESS:           OFF
--   DEMO_WORKSPACE:          main
--
-- Loaded workspace: Main Demo
--   Timeline: timeline.seq
--   Music: pop_punk_drums.track
--   Assets: assets.txt
-- Using workspace: main
-- Configuring done (0.0s)
-- Generating done (0.0s)
-- Build files have been written to: /Users/skal/demo/build_native
[ 50%] Built target procedural
[100%] Built target asset_packer
[100%] Built target seq_compiler
[100%] Built target tracker_compiler_host
Cross-compiling for Windows...
--
-- Build Configuration:
--   DEMO_SIZE_OPT:           ON
--   DEMO_STRIP_ALL:          ON
--   DEMO_FINAL_STRIP:        OFF
--   DEMO_STRIP_EXTERNAL_LIBS: OFF
--   DEMO_BUILD_TESTS:        OFF
--   DEMO_BUILD_TOOLS:        OFF
--   DEMO_ENABLE_COVERAGE:    OFF
--   DEMO_ENABLE_DEBUG_LOGS:  OFF
--   DEMO_HEADLESS:           OFF
--   DEMO_WORKSPACE:          main
--
-- Loaded workspace: Main Demo
--   Timeline: timeline.seq
--   Music: pop_punk_drums.track
--   Assets: assets.txt
-- Using workspace: main
-- Configuring done (0.0s)
-- Generating done (0.0s)
-- Build files have been written to: /Users/skal/demo/build_win
[  2%] Built target validate_uniforms_script
[  2%] Built target generate_timeline
[  4%] Built target generate_test_demo_timeline
[  4%] Built target generate_demo_assets
[  4%] Built target generate_test_assets
[  6%] Built target procedural
[  9%] Built target tracker_compiler_host
[ 10%] Validating uniform buffer sizes and alignments...
[ 11%] Built target generate_tracker_music
[ 13%] Built target generate_test_demo_music
[ 16%] Built target util
[ 28%] Built target 3d
[ 45%] Built target audio
[ 49%] Building CXX object CMakeFiles/gpu.dir/src/effects/heptagon_effect.cc.obj
[ 52%] Building CXX object CMakeFiles/gpu.dir/src/effects/gaussian_blur_effect.cc.obj
[ 54%] Building CXX object CMakeFiles/gpu.dir/src/effects/particles_effect.cc.obj
[ 54%] Building CXX object CMakeFiles/gpu.dir/src/effects/moving_ellipse_effect.cc.obj
[ 54%] Building CXX object CMakeFiles/gpu.dir/src/gpu/effect.cc.obj
[ 54%] Building CXX object CMakeFiles/gpu.dir/src/effects/passthrough_effect.cc.obj
[ 54%] Building CXX object CMakeFiles/gpu.dir/src/effects/particle_spray_effect.cc.obj
Validation Warning for 'CommonPostProcessUniforms': Matching WGSL struct not found.
Validation OK for 'FadeParams': Size 16 matches C++ expected size.
Validation OK for 'ThemeModulationParams': Size 16 matches C++ expected size.
Validation OK for 'GaussianBlurParams': Size 8 matches C++ expected size.
Validation OK for 'DistortParams': Size 8 matches C++ expected size.
Validation OK for 'CircleMaskParams': Size 16 matches C++ expected size.
[ 54%] Built target validate_uniforms
[ 55%] Building CXX object CMakeFiles/gpu.dir/src/effects/solarize_effect.cc.obj
[ 57%] Building CXX object CMakeFiles/gpu.dir/src/effects/scene1_effect.cc.obj
[ 57%] Building CXX object CMakeFiles/gpu.dir/src/effects/chroma_aberration_effect.cc.obj
[ 58%] Building CXX object CMakeFiles/gpu.dir/src/effects/vignette_effect.cc.obj
[ 59%] Building CXX object CMakeFiles/gpu.dir/src/gpu/post_process_helper.cc.obj
[ 60%] Building CXX object CMakeFiles/gpu.dir/src/gpu/shaders.cc.obj
[ 62%] Linking CXX static library libgpu.a
[ 77%] Built target gpu
[ 79%] Building CXX object CMakeFiles/demo64k.dir/src/app/main.cc.obj
[ 79%] Building CXX object CMakeFiles/test_demo.dir/src/app/test_demo.cc.obj
[ 80%] Building CXX object CMakeFiles/demo64k.dir/src/generated/timeline.cc.obj
[ 81%] Building CXX object CMakeFiles/test_demo.dir/src/generated/test_demo_timeline.cc.obj
[ 82%] Linking CXX executable test_demo.exe
[ 90%] Built target test_demo
[ 91%] Linking CXX executable demo64k.exe
[100%] Built target demo64k
Copying MinGW DLLs...
Crunching build_win/demo64k.exe...
                       Ultimate Packer for eXecutables
                          Copyright (C) 1996 - 2026
UPX 5.1.0       Markus Oberhumer, Laszlo Molnar & John Reiser    Jan 7th 2026

        File size         Ratio      Format      Name
   --------------------   ------   -----------   -----------
   7036416 ->   4680704   66.52%    win64/pe     demo64k_packed.exe

Packed 1 file.
------------------------------------------------
Size Report:
-rwxr-xr-x  1 skal  89939   6.7M Feb 14 14:55 build_win/demo64k.exe
-rwxr-xr-x  1 skal  89939   6.7M Feb 14 14:55 build_win/demo64k_stripped.exe
-rwxr-xr-x  1 skal  89939   4.5M Feb 14 14:55 build_win/demo64k_packed.exe
------------------------------------------------
Top 20 Largest Symbols (from unstripped):
------------------------------------------------
Build complete. Output: build_win/demo64k.exe

All checks passed successfully. script completes without errors.

This change streamlines the project's architecture without altering any functionality.

1 files changed, 94 insertions, 0 deletions

diff --git a/src/effects/flash_effect.cc b/src/effects/flash_effect.cc
new file mode 100644
index 0000000..235412d
--- /dev/null
+++ b/src/effects/flash_effect.cc
@@ -0,0 +1,94 @@
+// This file is part of the 64k demo project.
+// It implements the FlashEffect - brief flash on u.beat hits.
+// Now supports parameterized color with per-frame animation.
+
+#include "effects/flash_effect.h"
+#include "gpu/post_process_helper.h"
+#include <cmath>
+
+// Backward compatibility constructor (delegates to parameterized constructor)
+FlashEffect::FlashEffect(const GpuContext& ctx)
+    : FlashEffect(ctx, FlashEffectParams{}) {
+}
+
+// Parameterized constructor
+FlashEffect::FlashEffect(const GpuContext& ctx, const FlashEffectParams& params)
+    : PostProcessEffect(ctx), params_(params) {
+  const char* shader_code = R"(
+    struct VertexOutput {
+      @builtin(position) position: vec4<f32>,
+      @location(0) uv: vec2<f32>,
+    };
+
+    struct Uniforms {
+      flash_intensity: f32,
+      audio_intensity: f32,
+      flash_color: vec3<f32>,  // Parameterized color
+      _pad: f32,
+    };
+
+    @group(0) @binding(0) var inputSampler: sampler;
+    @group(0) @binding(1) var inputTexture: texture_2d<f32>;
+    @group(0) @binding(2) var<uniform> uniforms: Uniforms;
+
+    @vertex
+    fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+      var output: VertexOutput;
+      var pos = array<vec2<f32>, 3>(
+        vec2<f32>(-1.0, -1.0),
+        vec2<f32>(3.0, -1.0),
+        vec2<f32>(-1.0, 3.0)
+      );
+      output.position = vec4<f32>(pos[vertexIndex], 0.0, 1.0);
+      output.uv = pos[vertexIndex] * 0.5 + 0.5;
+      return output;
+    }
+
+    @fragment
+    fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+      let color = textureSample(inputTexture, inputSampler, input.uv);
+      // Use parameterized flash color instead of hardcoded white
+      var flashed = mix(color.rgb, uniforms.flash_color, uniforms.flash_intensity);
+      return vec4<f32>(flashed, color.a);
+    }
+  )";
+
+  pipeline_ =
+      create_post_process_pipeline(ctx_.device, ctx_.format, shader_code);
+  flash_uniforms_.init(ctx_.device);
+}
+
+void FlashEffect::update_bind_group(WGPUTextureView input_view) {
+  pp_update_bind_group(ctx_.device, pipeline_, &bind_group_, input_view,
+                       flash_uniforms_.get(), {});
+}
+
+void FlashEffect::render(WGPURenderPassEncoder pass,
+                         const CommonPostProcessUniforms& uniforms) {
+  // Trigger flash based on configured threshold
+  if (uniforms.audio_intensity > params_.trigger_threshold && flash_intensity_ < 0.2f) {
+    flash_intensity_ = 0.8f; // Trigger flash
+  }
+
+  // Decay based on configured rate
+  flash_intensity_ *= params_.decay_rate;
+
+  // *** PER-FRAME PARAMETER COMPUTATION ***
+  // Animate color based on time and beat
+  const float r = params_.color[0] * (0.5f + 0.5f * sinf(uniforms.time * 0.5f));
+  const float g = params_.color[1] * (0.5f + 0.5f * cosf(uniforms.time * 0.7f));
+  const float b = params_.color[2] * (1.0f + 0.3f * uniforms.beat_phase);
+
+  // Update uniforms with computed (animated) values
+  const FlashUniforms u = {
+      .flash_intensity = flash_intensity_,
+      .intensity = uniforms.audio_intensity,
+      ._pad1 = {0.0f, 0.0f}, // Padding for vec3 alignment
+      .color = {r, g, b},    // Time-dependent, computed every frame
+      ._pad2 = 0.0f};
+  flash_uniforms_.update(ctx_.queue, u);
+
+  wgpuRenderPassEncoderSetPipeline(pass, pipeline_);
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_, 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
+}