Refactor: factorize WGPU init code for 3D tests

Extracted duplicate WGPU initialization boilerplate from test_3d_physics,
test_3d_render, and test_mesh into shared helper (test_3d_helpers).

**Changes:**
- New: src/tests/common/test_3d_helpers.{h,cc} (~120 LOC)
- Removed ~280 LOC of duplicate init_wgpu() implementations
- Net savings: -141 LOC

**Benefits:**
- Single source of truth for surface+device initialization
- Eliminates cross-compile #ifdef duplication
- Easier maintenance for callback API changes

All 34 tests pass.

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

5 files changed, 138 insertions, 277 deletions

diff --git a/src/tests/3d/test_3d_physics.cc b/src/tests/3d/test_3d_physics.cc
index eb1f5ef..2ee5a4a 100644
--- a/src/tests/3d/test_3d_physics.cc
+++ b/src/tests/3d/test_3d_physics.cc
@@ -11,6 +11,7 @@
 #include "gpu/texture_manager.h"
 #include "platform/platform.h"
 #include "procedural/generator.h"
+#include "../common/test_3d_helpers.h"
 #include <cmath>
 #include <cstdio>
 #include <cstring>
@@ -25,100 +26,8 @@ static PhysicsSystem g_physics;
 static WGPUDevice g_device = nullptr;
 static WGPUQueue g_queue = nullptr;
 static WGPUSurface g_surface = nullptr;
-static WGPUAdapter g_adapter = nullptr;
 static WGPUTextureFormat g_format = WGPUTextureFormat_Undefined;
 
-// ... (init_wgpu implementation same as before)
-void init_wgpu(PlatformState* platform_state) {
-  WGPUInstance instance = wgpuCreateInstance(nullptr);
-  if (!instance) {
-    fprintf(stderr, "Failed to create WGPU instance.\n");
-    exit(1);
-  }
-
-  g_surface = platform_create_wgpu_surface(instance, platform_state);
-  if (!g_surface) {
-    fprintf(stderr, "Failed to create WGPU surface.\n");
-    exit(1);
-  }
-
-  WGPURequestAdapterOptions adapter_opts = {};
-  adapter_opts.compatibleSurface = g_surface;
-  adapter_opts.powerPreference = WGPUPowerPreference_HighPerformance;
-
-#if defined(DEMO_CROSS_COMPILE_WIN32)
-  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
-                       const char* message, void* userdata) {
-    if (status == WGPURequestAdapterStatus_Success) {
-      *(WGPUAdapter*)userdata = adapter;
-    }
-  };
-  wgpuInstanceRequestAdapter(instance, &adapter_opts, on_adapter, &g_adapter);
-#else
-  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
-                       WGPUStringView message, void* userdata, void* user2) {
-    (void)user2;
-    if (status == WGPURequestAdapterStatus_Success) {
-      *(WGPUAdapter*)userdata = adapter;
-    }
-  };
-  WGPURequestAdapterCallbackInfo adapter_cb = {};
-  adapter_cb.mode = WGPUCallbackMode_WaitAnyOnly;
-  adapter_cb.callback = on_adapter;
-  adapter_cb.userdata1 = &g_adapter;
-  wgpuInstanceRequestAdapter(instance, &adapter_opts, adapter_cb);
-#endif
-
-  while (!g_adapter) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  WGPUDeviceDescriptor device_desc = {};
-
-#if defined(DEMO_CROSS_COMPILE_WIN32)
-  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
-                      const char* message, void* userdata) {
-    if (status == WGPURequestDeviceStatus_Success) {
-      *(WGPUDevice*)userdata = device;
-    }
-  };
-  wgpuAdapterRequestDevice(g_adapter, &device_desc, on_device, &g_device);
-#else
-  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
-                      WGPUStringView message, void* userdata, void* user2) {
-    (void)user2;
-    if (status == WGPURequestDeviceStatus_Success) {
-      *(WGPUDevice*)userdata = device;
-    }
-  };
-  WGPURequestDeviceCallbackInfo device_cb = {};
-  device_cb.mode = WGPUCallbackMode_WaitAnyOnly;
-  device_cb.callback = on_device;
-  device_cb.userdata1 = &g_device;
-  wgpuAdapterRequestDevice(g_adapter, &device_desc, device_cb);
-#endif
-
-  while (!g_device) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  g_queue = wgpuDeviceGetQueue(g_device);
-
-  WGPUSurfaceCapabilities caps = {};
-  wgpuSurfaceGetCapabilities(g_surface, g_adapter, &caps);
-  g_format = caps.formats[0];
-
-  WGPUSurfaceConfiguration config = {};
-  config.device = g_device;
-  config.format = g_format;
-  config.usage = WGPUTextureUsage_RenderAttachment;
-  config.width = platform_state->width;
-  config.height = platform_state->height;
-  config.presentMode = WGPUPresentMode_Fifo;
-  config.alphaMode = WGPUCompositeAlphaMode_Opaque;
-  wgpuSurfaceConfigure(g_surface, &config);
-}
-
 void setup_scene() {
   g_scene.clear();
   srand(12345); // Fixed seed
@@ -205,8 +114,11 @@ int main(int argc, char** argv) {
 
   PlatformState platform_state = platform_init(false, 1280, 720);
 
-  // The test's own WGPU init sequence
-  init_wgpu(&platform_state);
+  WgpuSurfaceContext wgpu_ctx = init_wgpu_with_surface(&platform_state);
+  g_device = wgpu_ctx.device;
+  g_queue = wgpu_ctx.queue;
+  g_surface = wgpu_ctx.surface;
+  g_format = wgpu_ctx.format;
 
   InitShaderComposer();
 
diff --git a/src/tests/3d/test_3d_render.cc b/src/tests/3d/test_3d_render.cc
index eee46ba..49a265f 100644
--- a/src/tests/3d/test_3d_render.cc
+++ b/src/tests/3d/test_3d_render.cc
@@ -10,6 +10,7 @@
 #include "gpu/texture_manager.h"
 #include "platform/platform.h"
 #include "procedural/generator.h"
+#include "../common/test_3d_helpers.h"
 #include <cmath>
 #include <cstdio>
 #include <cstring>
@@ -23,100 +24,8 @@ static Camera g_camera;
 static WGPUDevice g_device = nullptr;
 static WGPUQueue g_queue = nullptr;
 static WGPUSurface g_surface = nullptr;
-static WGPUAdapter g_adapter = nullptr;
 static WGPUTextureFormat g_format = WGPUTextureFormat_Undefined;
 
-// ... (init_wgpu implementation same as before)
-void init_wgpu(PlatformState* platform_state) {
-  WGPUInstance instance = wgpuCreateInstance(nullptr);
-  if (!instance) {
-    fprintf(stderr, "Failed to create WGPU instance.\n");
-    exit(1);
-  }
-
-  g_surface = platform_create_wgpu_surface(instance, platform_state);
-  if (!g_surface) {
-    fprintf(stderr, "Failed to create WGPU surface.\n");
-    exit(1);
-  }
-
-  WGPURequestAdapterOptions adapter_opts = {};
-  adapter_opts.compatibleSurface = g_surface;
-  adapter_opts.powerPreference = WGPUPowerPreference_HighPerformance;
-
-#if defined(DEMO_CROSS_COMPILE_WIN32)
-  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
-                       const char* message, void* userdata) {
-    if (status == WGPURequestAdapterStatus_Success) {
-      *(WGPUAdapter*)userdata = adapter;
-    }
-  };
-  wgpuInstanceRequestAdapter(instance, &adapter_opts, on_adapter, &g_adapter);
-#else
-  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
-                       WGPUStringView message, void* userdata, void* user2) {
-    (void)user2;
-    if (status == WGPURequestAdapterStatus_Success) {
-      *(WGPUAdapter*)userdata = adapter;
-    }
-  };
-  WGPURequestAdapterCallbackInfo adapter_cb = {};
-  adapter_cb.mode = WGPUCallbackMode_WaitAnyOnly;
-  adapter_cb.callback = on_adapter;
-  adapter_cb.userdata1 = &g_adapter;
-  wgpuInstanceRequestAdapter(instance, &adapter_opts, adapter_cb);
-#endif
-
-  while (!g_adapter) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  WGPUDeviceDescriptor device_desc = {};
-
-#if defined(DEMO_CROSS_COMPILE_WIN32)
-  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
-                      const char* message, void* userdata) {
-    if (status == WGPURequestDeviceStatus_Success) {
-      *(WGPUDevice*)userdata = device;
-    }
-  };
-  wgpuAdapterRequestDevice(g_adapter, &device_desc, on_device, &g_device);
-#else
-  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
-                      WGPUStringView message, void* userdata, void* user2) {
-    (void)user2;
-    if (status == WGPURequestDeviceStatus_Success) {
-      *(WGPUDevice*)userdata = device;
-    }
-  };
-  WGPURequestDeviceCallbackInfo device_cb = {};
-  device_cb.mode = WGPUCallbackMode_WaitAnyOnly;
-  device_cb.callback = on_device;
-  device_cb.userdata1 = &g_device;
-  wgpuAdapterRequestDevice(g_adapter, &device_desc, device_cb);
-#endif
-
-  while (!g_device) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  g_queue = wgpuDeviceGetQueue(g_device);
-
-  WGPUSurfaceCapabilities caps = {};
-  wgpuSurfaceGetCapabilities(g_surface, g_adapter, &caps);
-  g_format = caps.formats[0];
-
-  WGPUSurfaceConfiguration config = {};
-  config.device = g_device;
-  config.format = g_format;
-  config.usage = WGPUTextureUsage_RenderAttachment;
-  config.width = platform_state->width;
-  config.height = platform_state->height;
-  config.presentMode = WGPUPresentMode_Fifo;
-  config.alphaMode = WGPUCompositeAlphaMode_Opaque;
-  wgpuSurfaceConfigure(g_surface, &config);
-}
-
 void setup_scene() {
   g_scene.clear();
   srand(12345); // Fixed seed
@@ -211,8 +120,11 @@ int main(int argc, char** argv) {
 
   PlatformState platform_state = platform_init(false, 1280, 720);
 
-  // The test's own WGPU init sequence
-  init_wgpu(&platform_state);
+  WgpuSurfaceContext wgpu_ctx = init_wgpu_with_surface(&platform_state);
+  g_device = wgpu_ctx.device;
+  g_queue = wgpu_ctx.queue;
+  g_surface = wgpu_ctx.surface;
+  g_format = wgpu_ctx.format;
 
   InitShaderComposer();
 
diff --git a/src/tests/3d/test_mesh.cc b/src/tests/3d/test_mesh.cc
index 2129bc8..0374ed8 100644
--- a/src/tests/3d/test_mesh.cc
+++ b/src/tests/3d/test_mesh.cc
@@ -10,6 +10,7 @@
 #include "platform/platform.h"
 #include "procedural/generator.h"
 #include "util/asset_manager_utils.h"
+#include "../common/test_3d_helpers.h"
 #include <algorithm>
 #include <cmath>
 #include <cstdio>
@@ -27,98 +28,11 @@ static Camera g_camera;
 static WGPUDevice g_device = nullptr;
 static WGPUQueue g_queue = nullptr;
 static WGPUSurface g_surface = nullptr;
-static WGPUAdapter g_adapter = nullptr;
 static WGPUTextureFormat g_format = WGPUTextureFormat_Undefined;
 
 // Test-specific storage for mesh buffers
 static Renderer3D::MeshGpuData g_mesh_gpu_data;
 
-// Callbacks for asynchronous WGPU initialization (matches test_3d_render.cc)
-void on_adapter_request_ended(WGPURequestAdapterStatus status,
-                              WGPUAdapter adapter, WGPUStringView message,
-                              void* userdata, void* user2) {
-  (void)user2;
-  if (status == WGPURequestAdapterStatus_Success) {
-    *(WGPUAdapter*)userdata = adapter;
-  } else {
-    fprintf(stderr,
-            "Failed to request adapter.\n"); // Avoid WGPUStringView::s issues
-  }
-}
-
-void on_device_request_ended(WGPURequestDeviceStatus status, WGPUDevice device,
-                             WGPUStringView message, void* userdata,
-                             void* user2) {
-  (void)user2;
-  if (status == WGPURequestDeviceStatus_Success) {
-    *(WGPUDevice*)userdata = device;
-  } else {
-    fprintf(stderr,
-            "Failed to request device.\n"); // Avoid WGPUStringView::s issues
-  }
-}
-
-// --- WGPU Boilerplate ---
-void init_wgpu(WGPUInstance instance, PlatformState* platform_state) {
-  if (!instance) {
-    fprintf(stderr, "Failed to create WGPU instance.\n");
-    exit(1);
-  }
-
-  g_surface = platform_create_wgpu_surface(instance, platform_state);
-  if (!g_surface) {
-    fprintf(stderr, "Failed to create WGPU surface.\n");
-    exit(1);
-  }
-
-  // Request Adapter
-  WGPURequestAdapterOptions adapter_opts = {};
-  adapter_opts.compatibleSurface = g_surface;
-  adapter_opts.powerPreference = WGPUPowerPreference_HighPerformance;
-
-  WGPURequestAdapterCallbackInfo adapter_callback_info = {};
-  adapter_callback_info.mode = WGPUCallbackMode_WaitAnyOnly;
-  adapter_callback_info.callback = on_adapter_request_ended;
-  adapter_callback_info.userdata1 = &g_adapter; // Corrected to userdata1
-
-  wgpuInstanceRequestAdapter(instance, &adapter_opts, adapter_callback_info);
-
-  // Busy-wait for adapter
-  while (!g_adapter) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  // Request Device
-  WGPUDeviceDescriptor device_desc = {};
-  WGPURequestDeviceCallbackInfo device_callback_info = {};
-  device_callback_info.mode = WGPUCallbackMode_WaitAnyOnly;
-  device_callback_info.callback = on_device_request_ended;
-  device_callback_info.userdata1 = &g_device; // Corrected to userdata1
-
-  wgpuAdapterRequestDevice(g_adapter, &device_desc, device_callback_info);
-
-  // Busy-wait for device
-  while (!g_device) {
-    platform_wgpu_wait_any(instance);
-  }
-
-  g_queue = wgpuDeviceGetQueue(g_device);
-
-  WGPUSurfaceCapabilities caps = {};
-  wgpuSurfaceGetCapabilities(g_surface, g_adapter, &caps);
-  g_format = caps.formats[0];
-
-  WGPUSurfaceConfiguration config = {};
-  config.device = g_device;
-  config.format = g_format;
-  config.usage = WGPUTextureUsage_RenderAttachment;
-  config.width = platform_state->width;
-  config.height = platform_state->height;
-  config.presentMode = WGPUPresentMode_Fifo;
-  config.alphaMode = WGPUCompositeAlphaMode_Opaque;
-  wgpuSurfaceConfigure(g_surface, &config);
-}
-
 // --- OBJ Loading Logic ---
 #include <cmath> // For std::sqrt
 
@@ -327,8 +241,11 @@ int main(int argc, char** argv) {
 
   PlatformState platform_state = platform_init(false, 1280, 720);
 
-  WGPUInstance instance = wgpuCreateInstance(nullptr);
-  init_wgpu(instance, &platform_state);
+  WgpuSurfaceContext wgpu_ctx = init_wgpu_with_surface(&platform_state);
+  g_device = wgpu_ctx.device;
+  g_queue = wgpu_ctx.queue;
+  g_surface = wgpu_ctx.surface;
+  g_format = wgpu_ctx.format;
   InitShaderComposer();
 
   g_renderer.init(g_device, g_queue, g_format);
diff --git a/src/tests/common/test_3d_helpers.cc b/src/tests/common/test_3d_helpers.cc
new file mode 100644
index 0000000..13e1cfe
--- /dev/null
+++ b/src/tests/common/test_3d_helpers.cc
@@ -0,0 +1,100 @@
+// This file is part of the 64k demo project.
+// Common WGPU initialization for 3D visual tests with surfaces.
+
+#include "test_3d_helpers.h"
+#include <cstdio>
+#include <cstdlib>
+
+WgpuSurfaceContext init_wgpu_with_surface(PlatformState* platform_state) {
+  WgpuSurfaceContext ctx = {};
+
+  WGPUInstance instance = wgpuCreateInstance(nullptr);
+  if (!instance) {
+    fprintf(stderr, "Failed to create WGPU instance.\n");
+    exit(1);
+  }
+
+  ctx.surface = platform_create_wgpu_surface(instance, platform_state);
+  if (!ctx.surface) {
+    fprintf(stderr, "Failed to create WGPU surface.\n");
+    exit(1);
+  }
+
+  WGPURequestAdapterOptions adapter_opts = {};
+  adapter_opts.compatibleSurface = ctx.surface;
+  adapter_opts.powerPreference = WGPUPowerPreference_HighPerformance;
+
+#if defined(DEMO_CROSS_COMPILE_WIN32)
+  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
+                       const char* message, void* userdata) {
+    if (status == WGPURequestAdapterStatus_Success) {
+      *(WGPUAdapter*)userdata = adapter;
+    }
+  };
+  wgpuInstanceRequestAdapter(instance, &adapter_opts, on_adapter, &ctx.adapter);
+#else
+  auto on_adapter = [](WGPURequestAdapterStatus status, WGPUAdapter adapter,
+                       WGPUStringView message, void* userdata, void* user2) {
+    (void)user2;
+    if (status == WGPURequestAdapterStatus_Success) {
+      *(WGPUAdapter*)userdata = adapter;
+    }
+  };
+  WGPURequestAdapterCallbackInfo adapter_cb = {};
+  adapter_cb.mode = WGPUCallbackMode_WaitAnyOnly;
+  adapter_cb.callback = on_adapter;
+  adapter_cb.userdata1 = &ctx.adapter;
+  wgpuInstanceRequestAdapter(instance, &adapter_opts, adapter_cb);
+#endif
+
+  while (!ctx.adapter) {
+    platform_wgpu_wait_any(instance);
+  }
+
+  WGPUDeviceDescriptor device_desc = {};
+
+#if defined(DEMO_CROSS_COMPILE_WIN32)
+  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
+                      const char* message, void* userdata) {
+    if (status == WGPURequestDeviceStatus_Success) {
+      *(WGPUDevice*)userdata = device;
+    }
+  };
+  wgpuAdapterRequestDevice(ctx.adapter, &device_desc, on_device, &ctx.device);
+#else
+  auto on_device = [](WGPURequestDeviceStatus status, WGPUDevice device,
+                      WGPUStringView message, void* userdata, void* user2) {
+    (void)user2;
+    if (status == WGPURequestDeviceStatus_Success) {
+      *(WGPUDevice*)userdata = device;
+    }
+  };
+  WGPURequestDeviceCallbackInfo device_cb = {};
+  device_cb.mode = WGPUCallbackMode_WaitAnyOnly;
+  device_cb.callback = on_device;
+  device_cb.userdata1 = &ctx.device;
+  wgpuAdapterRequestDevice(ctx.adapter, &device_desc, device_cb);
+#endif
+
+  while (!ctx.device) {
+    platform_wgpu_wait_any(instance);
+  }
+
+  ctx.queue = wgpuDeviceGetQueue(ctx.device);
+
+  WGPUSurfaceCapabilities caps = {};
+  wgpuSurfaceGetCapabilities(ctx.surface, ctx.adapter, &caps);
+  ctx.format = caps.formats[0];
+
+  WGPUSurfaceConfiguration config = {};
+  config.device = ctx.device;
+  config.format = ctx.format;
+  config.usage = WGPUTextureUsage_RenderAttachment;
+  config.width = platform_state->width;
+  config.height = platform_state->height;
+  config.presentMode = WGPUPresentMode_Fifo;
+  config.alphaMode = WGPUCompositeAlphaMode_Opaque;
+  wgpuSurfaceConfigure(ctx.surface, &config);
+
+  return ctx;
+}
diff --git a/src/tests/common/test_3d_helpers.h b/src/tests/common/test_3d_helpers.h
new file mode 100644
index 0000000..5e9c72c
--- /dev/null
+++ b/src/tests/common/test_3d_helpers.h
@@ -0,0 +1,20 @@
+// This file is part of the 64k demo project.
+// Common WGPU initialization for 3D visual tests with surfaces.
+
+#pragma once
+
+#include "platform/platform.h"
+#include <webgpu.h>
+
+// Result of WGPU initialization with surface
+struct WgpuSurfaceContext {
+  WGPUDevice device;
+  WGPUQueue queue;
+  WGPUSurface surface;
+  WGPUAdapter adapter;
+  WGPUTextureFormat format;
+};
+
+// Initialize WGPU with surface for rendering tests
+// Returns context with device/queue/surface/adapter/format
+WgpuSurfaceContext init_wgpu_with_surface(PlatformState* platform_state);