fix(wgpu): build + render the demo on macOS (Metal surface)

[apotema]

What

Make the WebGPU backend build and render on macOS — both the standalone demo and engine-generated games.

The break

backends/wgpu/example/build.zig was inherited from the old Dawn-based wiring (absorbed from labelle-cli) and still linked a nonexistent zdawn artifact plus a dawn system library and dawn_aarch64_macos/dawn_x86_64_macos deps. Since the backend migrated to wgpu-native (wgpu_native_zig, #228/#287), zig build in the example panicked:

thread panic: unable to find artifact 'zdawn'  (available artifact: 'glfw')

The same missing-frameworks problem also lived in the assembler's link_wgpu build template, so any game generated with .backend = .wgpu would fail to link on macOS too.

The fix

• example/build.zig — drop all Dawn references. wgpu_native_zig's wgpu module already embeds libwgpu_native.a via addObjectFile, and that module is imported by the backend's gfx/window modules, so the native runtime travels into the exe transitively. The example only needs the glfw artifact plus, on Apple targets, the Metal/QuartzCore/Foundation frameworks wgpu-native links at the Compile step (upstream links them per-Compile, not on the module).
• src/window.zig — surface creation was Win32-only. Add the Apple path: pull the Cocoa NSWindow from GLFW (getCocoaWindow), attach a fresh CAMetalLayer to its content view via three objc_msgSend calls, and feed it to surfaceDescriptorFromMetalLayer. initGpu is refactored to a per-OS createSurface() so the adapter → device → pipeline spine stays shared.
• src/templates/build_zig.txt (link_wgpu) — link Foundation/QuartzCore/Metal on Apple targets in generated engine builds, mirroring the example fix.

Verification (macOS arm64, Zig 0.16.0)

• backends/wgpu → zig build test: 14/14 pass.
• backends/wgpu/example → zig build: produces wgpu-demo (links the wgpu-native static lib); running it opens a window and runs the acquire → render → present loop with no warnings — previously it logged surface creation only wired for Windows; rendering disabled and spammed shape batch full (batch never drained). The clean run means gpu_ready is set (full GPU spine initialized) and the shape batch drains each frame.
• Engine end-to-end: regenerated the gizmo-rendered Ricochet game with .backend = .wgpu. zig build links cleanly; the binary opens a window and runs the full engine loop (waves, physics, gizmo rendering through the wgpu shape path) for the whole run with zero wgpu/render warnings.

Assembler zig build + zig build test stay green. Windows path is unchanged.

[gemini-code-assist]

Code Review

This pull request adds macOS and iOS support to the WGPU backend. It updates the build configuration to link macOS system frameworks (Foundation, QuartzCore, and Metal) instead of Dawn, and implements macOS surface creation in window.zig by dynamically attaching a CAMetalLayer to the GLFW Cocoa window using the Objective-C runtime. A critical compilation issue was identified in window.zig where the lowercase .c calling convention is used instead of the uppercase .C.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In Zig, the calling convention for C is represented by the uppercase .C (i.e., callconv(.C)), not lowercase .c. Using .c will result in a compilation error because std.builtin.CallingConvention does not contain a lowercase c member.

    const msgId = @as(*const fn (ObjcId, ?*anyopaque) callconv(.C) ObjcId, @ptrCast(&objc_msgSend));
    const msgSetBool = @as(*const fn (ObjcId, ?*anyopaque, i8) callconv(.C) void, @ptrCast(&objc_msgSend));
    const msgSetId = @as(*const fn (ObjcId, ?*anyopaque, ObjcId) callconv(.C) void, @ptrCast(&objc_msgSend));

[cursor]

PR Summary

Medium Risk
Touches native linking and low-level Cocoa/Metal surface setup on the render path; Windows behavior is unchanged and CI adds build-only guards.

Overview
Restores macOS WebGPU builds and rendering by aligning linking with wgpu-native (no Dawn/zdawn) and adding a Metal-backed surface path.

The standalone wgpu demo build.zig stops linking the missing zdawn artifact and Dawn system libs; it keeps GLFW and, on macOS/iOS, links Foundation, QuartzCore, and Metal so libwgpu_native.a resolves. window.zig refactors GPU init to createSurface(): Windows still uses Win32 HWND; macOS gets Cocoa NSWindow from GLFW, attaches a CAMetalLayer via minimal Objective-C runtime calls, and uses surfaceDescriptorFromMetalLayer. Failed surface creation now releases the wgpu instance to avoid leaks on unsupported platforms.

Generated games using .backend = .wgpu get the same Apple framework links in the link_wgpu section of build_zig.txt.

CI re-enables backends/wgpu zig build test, adds a macOS-only backends/wgpu/example zig build, and greps the generated wgpu example build.zig for the three framework links on Linux so template regressions are caught without an Apple runner.

^{Reviewed by Cursor Bugbot for commit 38ae3b7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c45f039. Configure here.}

[apotema]

Bot triage:

• Cursor (instance leak on unsupported platforms) — valid, fixed in 38ae3b7. initGpu now releases the wgpu instance (and nulls it) when createSurface returns null, so the Linux/unsupported path no longer leaks.
• Gemini (callconv(.c) → .C) — declined. Zig 0.16 uses the lowercase .c calling convention; .C is the pre-0.15 spelling. The surrounding code already uses callconv(.winapi), the zglfw dep uses callconv(.c), and this branch builds and links on macOS arm64 — .C would not compile.

Added CI so this class of break can't ship silently again: the standalone backends/wgpu/example now builds on the macos-latest runner (real Metal-framework link + CAMetalLayer surface compile), and the Linux examples-integration step asserts the generated wgpu_desktop/build.zig links Foundation/QuartzCore/Metal (locks the link_wgpu template).