feat(3d): Add scaffolding for visual debugging (Task #18a)

- Added 'src/3d/visual_debug.h/cc' to implement wireframe rendering.
- Integrated VisualDebug into Renderer3D with a static global toggle.
- Added '--debug' command-line option to 'demo64k' and 'test_3d_render' to enable wireframes.
- Updated 'src/gpu/effects/hybrid_3d_effect.h' to expose the debug setter (reverted later as static method used).
- Ensured full cross-platform compatibility (native and Windows) for the new debug module.
- All code guarded by STRIP_ALL for final release.

1 files changed, 49 insertions, 0 deletions

diff --git a/src/3d/visual_debug.h b/src/3d/visual_debug.h
new file mode 100644
index 0000000..c757de3
--- /dev/null
+++ b/src/3d/visual_debug.h
@@ -0,0 +1,49 @@
+// This file is part of the 64k demo project.
+// It provides visual debugging tools, such as wireframe rendering.
+// This entire module is excluded when STRIP_ALL is defined.
+
+#pragma once
+
+#if !defined(STRIP_ALL)
+
+#include "util/mini_math.h"
+#include "gpu/gpu.h"
+#include <vector>
+
+struct DebugLine {
+  vec3 start;
+  vec3 end;
+  vec3 color;
+};
+
+class VisualDebug {
+public:
+  void init(WGPUDevice device, WGPUTextureFormat format);
+  void shutdown();
+
+  // Queue a wireframe box for rendering this frame
+  void add_box(const vec3& center, const vec3& extent, const vec3& color);
+
+  // Render all queued primitives and clear the queue
+  void render(WGPURenderPassEncoder pass, const mat4& view_proj);
+
+private:
+  WGPUDevice device_ = nullptr;
+  WGPURenderPipeline pipeline_ = nullptr;
+  WGPUBindGroupLayout bind_group_layout_ = nullptr;
+  
+  std::vector<DebugLine> lines_;
+  
+  // Uniform buffer for ViewProjection matrix
+  WGPUBuffer uniform_buffer_ = nullptr;
+  WGPUBindGroup bind_group_ = nullptr;
+
+  // Vertex buffer for line segments
+  WGPUBuffer vertex_buffer_ = nullptr;
+  size_t vertex_buffer_capacity_ = 0;
+
+  void create_pipeline(WGPUTextureFormat format);
+  void update_buffers(const mat4& view_proj);
+};
+
+#endif // !defined(STRIP_ALL)