fix: Surface API contract enforcement + Metal checkptr (#280, #281)

.github/workflows/ci.yml

@@ -59,11 +59,11 @@ jobs:
         go-version: ${{ matrix.go-version }}
         cache: true
 
-    - name: Set up Android SDK
-      uses: android-actions/setup-android@v3
+    - name: Accept Android SDK licenses
+      run: yes | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --licenses > /dev/null 2>&1 || true
 
     - name: Install Android NDK r29
-      run: sdkmanager 'ndk;29.0.14206865'
+      run: $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager --install 'ndk;29.0.14206865'
 
     - name: Check Android arm64 source, tests, and ELF dependencies
       env:
@@ -102,6 +102,34 @@ jobs:
     - name: Build all packages
       run: go build ./...
 
+  # Cross-compile verification — ADR-047 unified public API
+  # Ensures Surface (and other build-tagged types) compile on all targets.
+  # Native is already covered by the build job; this adds browser and rust.
+  cross-compile:
+    name: Cross-compile - ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - { goos: js, goarch: wasm, tags: '', name: 'browser' }
+          - { goos: linux, goarch: amd64, tags: 'rust', name: 'rust' }
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.25'
+        cache: true
+
+    - name: Cross-compile ${{ matrix.name }} backend
+      env:
+        GOOS: ${{ matrix.goos }}
+        GOARCH: ${{ matrix.goarch }}
+        CGO_ENABLED: 0
+      run: go build ${{ matrix.tags && format('-tags={0}', matrix.tags) || '' }} .
+
   # Unit tests - Cross-platform
   test:
     name: Test - ${{ matrix.os }}

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.24] - 2026-07-28
+
+### Fixed
+
+- **Browser/Rust Surface missing methods** — `PresentPixels`, `WritePixels`,
+  `SetPrepareFrame`, and `SetPresentsWithTransaction` now exist on all backends.
+  Missing methods return clear errors or no-op, matching ADR-047 (unified public
+  API). Fixes WASM build failure introduced by gogpu PR #370. (#281)
+
+- **Metal checkptr abort under `-race`** — ObjC block callback trampolines used
+  `unsafe.Pointer(blockPtr + 32)` which violates Go's pointer provenance rules.
+  Replaced with `unsafe.Add(unsafe.Pointer(blockPtr), 32)` (Go 1.17+) at all 4
+  block callback locations. `go test -race` now works on Metal compute. (#280)
+
+### Added
+
+- **Compile-time Surface API contract** — anonymous interface assertion
+  (`var _ interface{...} = (*Surface)(nil)`) in each backend file enforces that
+  all public methods exist at compile time (ADR-047 enforcement).
+
+- **CI cross-compile job** — `GOOS=js GOARCH=wasm` (browser) and `-tags=rust`
+  (Rust FFI) builds added to CI pipeline. Missing Surface methods now fail the
+  PR, not the downstream consumer.
+
 ## [0.30.23] - 2026-07-26
 
 ### Fixed

hal/dx12/command.go

@@ -1029,8 +1029,6 @@ func needsExplicitBarrier(current, target d3d12.D3D12_RESOURCE_STATES) bool {
 	return true
 }
 
-
-
 func resolveSubresourceIndex(view *TextureView) uint32 {
 	if view == nil || view.texture == nil {
 		return 0

hal/metal/objc.go

@@ -648,7 +648,7 @@ func getSharedEventBlockInvoke() uintptr {
 			}
 			// Read blockID from the block literal at the fixed offset.
 			// Offset: isa(8) + flags(4) + reserved(4) + invoke(8) + descriptor(8) = 32 bytes
-			blockID := *(*uint64)(unsafe.Pointer(blockPtr + 32)) //nolint:govet // Required for ObjC block ABI access
+			blockID := *(*uint64)(unsafe.Add(unsafe.Pointer(blockPtr), 32))
 
 			hal.Logger().Debug("metal: shared event notification fired", "blockID", blockID)
 
@@ -751,7 +751,7 @@ func getCompletedHandlerBlockInvoke() uintptr {
 			}
 			// Read blockID from the block literal at the fixed offset.
 			// Offset: isa(8) + flags(4) + reserved(4) + invoke(8) + descriptor(8) = 32 bytes
-			blockID := *(*uint64)(unsafe.Pointer(blockPtr + 32)) //nolint:govet // Required for ObjC block ABI access
+			blockID := *(*uint64)(unsafe.Add(unsafe.Pointer(blockPtr), 32))
 
 			hal.Logger().Debug("metal: completion handler fired", "blockID", blockID)
 
@@ -847,7 +847,7 @@ func getFrameCompletionBlockInvoke() uintptr {
 			}
 			// Read blockID from the block literal at the fixed offset.
 			// Offset: isa(8) + flags(4) + reserved(4) + invoke(8) + descriptor(8) = 32 bytes
-			blockID := *(*uint64)(unsafe.Pointer(blockPtr + 32)) //nolint:govet // Required for ObjC block ABI access
+			blockID := *(*uint64)(unsafe.Add(unsafe.Pointer(blockPtr), 32))
 
 			hal.Logger().Debug("metal: frame completion fired", "blockID", blockID)
 
@@ -955,7 +955,7 @@ func getGPUCompletionBlockInvoke() uintptr {
 			}
 			// Read blockID from the block literal at the fixed offset.
 			// Offset: isa(8) + flags(4) + reserved(4) + invoke(8) + descriptor(8) = 32 bytes
-			blockID := *(*uint64)(unsafe.Pointer(blockPtr + 32)) //nolint:govet // Required for ObjC block ABI access
+			blockID := *(*uint64)(unsafe.Add(unsafe.Pointer(blockPtr), 32))
 
 			hal.Logger().Debug("metal: GPU completion tracking fired", "blockID", blockID)
 

scripts/check-android-arm64-preview.sh

@@ -52,7 +52,7 @@ require_checkout() {
 }
 
 goffi_module=github.com/go-webgpu/goffi
-goffi_version=v0.6.1
+goffi_version=v0.6.2
 (
 	cd "$root"
 	GOWORK=off go mod download "$goffi_module@$goffi_version"

surface_browser.go

@@ -3,13 +3,30 @@
 package wgpu
 
 import (
+	"errors"
 	"fmt"
 	"image"
 	"syscall/js"
 
 	"github.com/gogpu/wgpu/internal/browser"
 )
 
+// Compile-time assertion: Surface must implement all public API methods (ADR-047).
+var _ interface {
+	Configure(*Device, *SurfaceConfiguration) error
+	Unconfigure()
+	GetCurrentTexture() (*SurfaceTexture, bool, error)
+	Present(*SurfaceTexture) error
+	PresentWithDamage(*SurfaceTexture, []image.Rectangle) error
+	PresentPixels([]byte, uint32, uint32, []image.Rectangle) error
+	WritePixels([]byte, uint32, uint32) error
+	ReadPixels() ([]byte, error)
+	ActualExtent() (uint32, uint32)
+	DiscardTexture()
+	SetPresentsWithTransaction(bool)
+	Release()
+} = (*Surface)(nil)
+
 // Surface represents a platform rendering surface.
 // On browser, this wraps an HTMLCanvasElement + GPUCanvasContext.
 //
@@ -257,6 +274,26 @@ func (s *Surface) DiscardTexture() {
 	// No-op on browser. Cannot discard the texture.
 }
 
+// PresentPixels is not supported on browser backend.
+// Software-backend extension for direct pixel presentation.
+func (s *Surface) PresentPixels(_ []byte, _, _ uint32, _ []image.Rectangle) error {
+	return errors.New("wgpu: PresentPixels is not supported on the browser backend")
+}
+
+// WritePixels is not supported on browser backend.
+// Software-backend extension for direct framebuffer write.
+func (s *Surface) WritePixels(_ []byte, _, _ uint32) error {
+	return errors.New("wgpu: WritePixels is not supported on the browser backend")
+}
+
+// SetPrepareFrame is a no-op on browser backend.
+// Browser surfaces use requestAnimationFrame for frame timing.
+func (s *Surface) SetPrepareFrame(_ any) {}
+
+// SetPresentsWithTransaction is a no-op on browser backend.
+// Core Animation transactions are macOS-only.
+func (s *Surface) SetPresentsWithTransaction(_ bool) {}
+
 // Release releases the surface.
 func (s *Surface) Release() {
 	if s.released {

surface_native.go

@@ -14,6 +14,22 @@ import (
 	"github.com/gogpu/wgpu/hal"
 )
 
+// Compile-time assertion: Surface must implement all public API methods (ADR-047).
+var _ interface {
+	Configure(*Device, *SurfaceConfiguration) error
+	Unconfigure()
+	GetCurrentTexture() (*SurfaceTexture, bool, error)
+	Present(*SurfaceTexture) error
+	PresentWithDamage(*SurfaceTexture, []image.Rectangle) error
+	PresentPixels([]byte, uint32, uint32, []image.Rectangle) error
+	WritePixels([]byte, uint32, uint32) error
+	ReadPixels() ([]byte, error)
+	ActualExtent() (uint32, uint32)
+	DiscardTexture()
+	SetPresentsWithTransaction(bool)
+	Release()
+} = (*Surface)(nil)
+
 const (
 	platformWindows = "windows"
 	platformDarwin  = "darwin"

surface_rust.go

@@ -3,12 +3,29 @@
 package wgpu
 
 import (
+	"errors"
 	"fmt"
 	"image"
 
 	rwgpu "github.com/go-webgpu/webgpu/wgpu"
 )
 
+// Compile-time assertion: Surface must implement all public API methods (ADR-047).
+var _ interface {
+	Configure(*Device, *SurfaceConfiguration) error
+	Unconfigure()
+	GetCurrentTexture() (*SurfaceTexture, bool, error)
+	Present(*SurfaceTexture) error
+	PresentWithDamage(*SurfaceTexture, []image.Rectangle) error
+	PresentPixels([]byte, uint32, uint32, []image.Rectangle) error
+	WritePixels([]byte, uint32, uint32) error
+	ReadPixels() ([]byte, error)
+	ActualExtent() (uint32, uint32)
+	DiscardTexture()
+	SetPresentsWithTransaction(bool)
+	Release()
+} = (*Surface)(nil)
+
 // Surface represents a platform rendering surface.
 // On Rust backend, this wraps go-webgpu/webgpu Surface.
 type Surface struct {
@@ -193,6 +210,22 @@ func (s *Surface) DiscardTexture() {
 	// No-op: wgpu-native does not support texture discard.
 }
 
+// PresentPixels is not supported on Rust FFI backend.
+// Software-backend extension for direct pixel presentation.
+func (s *Surface) PresentPixels(_ []byte, _, _ uint32, _ []image.Rectangle) error {
+	return errors.New("wgpu: PresentPixels is not supported on the Rust backend")
+}
+
+// WritePixels is not supported on Rust FFI backend.
+// Software-backend extension for direct framebuffer write.
+func (s *Surface) WritePixels(_ []byte, _, _ uint32) error {
+	return errors.New("wgpu: WritePixels is not supported on the Rust backend")
+}
+
+// SetPresentsWithTransaction is a no-op on Rust backend.
+// Core Animation transactions are macOS-only.
+func (s *Surface) SetPresentsWithTransaction(_ bool) {}
+
 // Release releases the surface.
 func (s *Surface) Release() {
 	if s.released {