All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

• deps: goffi v0.6.2 → v0.6.3 — ARM64 HFA return checkptr crash fix, 9-16B struct return silent corruption fix (reported by @jbunds on Apple M1)

• Android ANativeWindow* surface creation through Instance.CreateSurfaceFromAndroidNativeWindow, including v29 wire-layout and zero-handle validation tests (#24 by @besmpl)
• Queue.GetTimestampPeriod() — returns GPU timestamp tick duration in nanoseconds via platform-correct float32 ABI path (#23 by @besmpl)
• float32Proc interface and shared callFloat32 path for procedures with native float returns

• macOS/Linux: RequestAdapter no longer hangs — callback entry points now correctly reconstruct WGPUStringView from two integer registers on Unix amd64/arm64 and Windows ARM64, preserving userdata for request completion. Windows x64 retains its indirect-aggregate convention. Closes #17 (#25 by @besmpl)
• go vet warning in loader_windows.go — use ptrFromUintptr for DLL function address conversion
• Consolidate three separate require directives in go.mod into a single block

• deps: goffi v0.6.0 → v0.6.2 — Windows x64 float return via XMM0 capture, Android ARM64 preview

• deps: goffi v0.5.2 → v0.6.0 — assembly-level errno capture, callback stack safety fix, zero-allocation FFI
• deps: gputypes v0.5.0 → v0.5.1
• deps: golang.org/x/sys v0.42.0 → v0.47.0

• Adapt to goffi v0.6.0 breaking change: CallFunction now returns (syscall.Errno, error)
• Fix all golangci-lint issues: unchecked Buffer.Unmap() errors in examples, os.Remove in setup, variable shadowing

• errno capture — first pure-Go FFI with correct errno on Linux (captured in assembly trampoline, ~3-5ns overhead)
• Callback stack fix — sync.Pool + runtime.Pinner prevents goroutine stack move corruption during C callbacks
• Zero-allocation FFI — ABI-safe struct layout eliminates allocations in steady state

• Security: HTTP download timeout (120s) — was: no timeout, hangs forever on network issues
• Security: Decompression bomb protection via io.LimitReader (200MB cap, gosec G110)
• Security: HTTP status code validation — was: no check for 404/500 responses
• Correctness: dst.Close() error checked on write path — was: unchecked, corrupted library on Windows
• Correctness: macOS prints DYLD_LIBRARY_PATH — was: LD_LIBRARY_PATH (wrong for macOS)
• Correctness: wgpu.Init() searches ./lib/ directory — auto-setup default location now auto-discovered

• Download progress indicator with Content-Length (MB)
• 10 new tests: Download() (happy/404/network error), FindLibrary() (env/missing/lib-dir)
• Package documentation for internal/nativelib
• README: WGPU_NATIVE_PATH instructions for all platforms after auto-setup

• Auto-setup tool — go run github.com/go-webgpu/webgpu/cmd/setup@latest downloads correct wgpu-native binary for your platform
• setup package — public API: setup.Install(dir), setup.FindLibrary(), setup.Version
• internal/nativelib — platform detection, download, zip extraction with tests

• deps: goffi v0.5.0 → v0.5.2

• wgpu-native v29.0.0.0: Migrated from v27.0.4.0 to v29.0.0.0 with stable webgpu-headers
• API redesign: All Create* methods now return (*T, error) instead of *T
• Method renames: GetQueue() → Queue(), GetSize() → Size(), GetLimits() → Limits(), etc.
• Struct layout changes: Limits field order fixed (ABI-breaking), VertexBufferLayout gains nextInChain
• Removed types: SupportedLimits, ChainedStructOut, InstanceCapabilities
• Enum changes: SurfaceGetCurrentTextureStatus simplified, InstanceFlag_Default semantic change
• gputypes aliases: Types re-exported for single-import ergonomics
• Buffer.MapAsync signature changed: (mode, offset, size) (*MapPending, error) — device argument removed, now stored in Buffer
• Buffer.Unmap() returns error (always nil per WebGPU spec; signature matches gogpu/wgpu)
• Queue.Submit returns (uint64, error) — submission index via wgpuQueueSubmitForIndex extension
• Adapter.Limits() returns Limits value (not pointer, no error) — cached at creation
• Device.Limits() returns Limits value (not pointer, no error) — cached at creation
• BindGroupLayoutEntry uses pointer sub-layouts (*BufferBindingLayout, *SamplerBindingLayout, etc.)
• SamplerDescriptor.MaxAnisotropy renamed to Anisotropy
• Surface.Configure(device, config) error — device is now a separate first argument
• Surface.GetCurrentTexture() returns (*SurfaceTexture, bool, error) — added suboptimal flag
• *Surface.Present(texture ...SurfaceTexture) error — takes optional texture argument

• 271 enterprise ABI verification tests (TestABI*)
• gputypes type aliases and constant re-exports in wgpu package
• New v29 API functions: GetFeatures, GetInstanceFeatures, BufferReadMappedRange, etc.
• New enums: InstanceFeatureName, ComponentSwizzle, PredefinedColorSpace, ToneMappingMode
• New instance flags: GPUBasedValidation, Debugging, AdvancedDebugging, WithEnv
• Buffer.Map(ctx, mode, offset, size) error — context-aware blocking mapping; drives Device.Poll internally
• Buffer.MapAsync(mode, offset, size) (*MapPending, error) — truly non-blocking, resolves on next Device.Poll
• Buffer.MappedRange(offset, size) (*MappedRange, error) — type-safe view over mapped memory
• MapPending type with Status() (ready bool, err error) and Wait(ctx) error methods
• MappedRange type with Bytes() []byte, Len() int, and Offset() uint64 methods
• Queue.Submit returns submission index uint64 via wgpuQueueSubmitForIndex wgpu-native extension
• ImageCopyTexture — Go-typed descriptor for texture copy/write source (holds *Texture)
• ImageDataLayout — Go-typed buffer layout descriptor for WriteTexture / copy operations
• BufferTextureCopy — region descriptor combining ImageCopyTexture + ImageDataLayout + extent
• TextureCopy — region descriptor for texture-to-texture copies
• CommandEncoder.CopyTextureToBuffer(src *Texture, dst *Buffer, regions []BufferTextureCopy) — region-based copy

• convert.go: Removed 6 identity converters (TextureFormat now matches v29 natively)
• wgpuAdapterEnumerateFeatures → wgpuAdapterGetFeatures (single-call pattern)
• PushConstants → Immediates rename throughout
• Buffer now stores *Device reference internally for Poll-driven blocking Map
• All public descriptors use Go-idiomatic types: string labels, bool flags, pointer sub-structs, slice fields

• SupportedLimits wrapper struct
• ChainedStructOut type (aliased to ChainedStruct)
• InstanceCapabilities struct
• DX11 backend support (InstanceBackendDX11)
• SurfaceGetCurrentTextureStatusOutOfMemory, SurfaceGetCurrentTextureStatusDeviceLost

• wgpu-native: v27.0.4.0 → v29.0.0.0
• goffi: v0.5.0 (unchanged)
• gputypes: v0.3.0 (unchanged)

• Update goffi v0.4.2 → v0.5.0 — Windows ARM64 (Snapdragon X) and FreeBSD amd64 support
• Update gputypes v0.2.0 → v0.3.0 — TextureUsage.ContainsUnknownBits() method
• Update golang.org/x/sys v0.41.0 → v0.42.0

• Update goffi v0.4.1 → v0.4.2 — purego compatibility fix (nofakecgo build tag for _cgo_init linker collision)
• Update golang.org/x/sys v0.40.0 → v0.41.0

• Update goffi v0.4.0 → v0.4.1 — ABI compliance hotfix (float32 encoding, stack spill for 7+ args, struct return, runtime.KeepAlive)

• Null handle guards on all public FFI methods — prevents SIGSEGV when passing nil/released objects
• 85 null guard tests (TestNullGuard_*) — CI-safe, no GPU required
• WGPU_NATIVE_PATH env var — override library path for custom wgpu-native locations
• ptrFromUintptr helper — eliminates all go vet unsafe.Pointer warnings in FFI code

• loadLibrary now returns (Library, error) — proper error propagation on init failure
• Windows: eager DLL loading via dll.Load() — errors at Init() instead of first FFI call
• Init() returns descriptive error messages with library path and override hint
• CI: wgpu-native binary downloaded in all workflows — tests run against real library, no skips
• CI: removed -unsafeptr=false go vet workaround — all warnings properly fixed

• 15 go vet warnings — all possible misuse of unsafe.Pointer eliminated via ptrFromUintptr
• Silent library loading failures — Init() now properly reports missing DLL/so/dylib

• goffi: v0.3.9 → v0.4.0 (crosscall2 integration for C-thread callbacks, fakecgo trampoline fixes)

• goffi: v0.3.8 → v0.3.9 (ARM64 callback trampoline fix, symbol rename to avoid linker collision)

• Surface.GetCapabilities() — query supported formats, present modes, alpha modes
• Device.GetFeatures() — enumerate all features enabled on the device
• Device.HasFeature() — check if a specific feature is enabled
• Device.GetLimits() — retrieve device limits (experimental, may return error)
• Typed error system — WGPUError with errors.Is()/errors.As() support
• Sentinel errors — ErrValidation, ErrOutOfMemory, ErrInternal, ErrDeviceLost
• Resource leak detection — SetDebugMode(true), ReportLeaks(), zero overhead when disabled
• Thread safety documentation — doc.go with threading model, safe/unsafe operations
• Fuzz testing — 14 fuzz targets for FFI boundary (enum conversions, struct sizes, math)
• API stability policy — STABILITY.md with stable/experimental classification
• Comprehensive godoc — all exported symbols documented for pkg.go.dev
• Release automation — GitHub Actions workflow for automated release on tag push

• Error-returning functions now use checkInit() instead of mustInit() panic
• PopErrorScope deprecated in favor of PopErrorScopeAsync
• Package doc consolidated into single doc.go (no more duplicate package comments)
• CONTRIBUTING.md expanded with architecture, error handling, fuzz testing, stability sections

• Struct size assertions for C ABI compatibility (DrawIndirectArgs, StringView, etc.)

• goffi: v0.3.7 → v0.3.8
• golang.org/x/sys: v0.39.0 → v0.40.0

• BREAKING: All WebGPU types now use github.com/gogpu/gputypes directly
  • TextureFormat, BufferUsage, ShaderStage, etc. are now from gputypes
  • Enum values now match webgpu.h specification (fixes compatibility issues)
  • Example: wgpu.TextureFormatBGRA8Unorm → gputypes.TextureFormatBGRA8Unorm
• goffi: v0.3.7 (ARM64 Darwin improvements)

• Integration with gogpu ecosystem via gputypes
• Full webgpu.h spec compliance for enum values
• Comprehensive conversion layer (wgpu/convert.go) for wgpu-native v27 compatibility
  • TextureFormat (~45 formats), VertexFormat (~30 formats)
  • VertexStepMode, TextureSampleType, TextureViewDimension, StorageTextureAccess
  • Wire structs with correct FFI padding (uint64 flags)

• TextureFormat enum values mismatch (BGRA8Unorm was 0x17, now correct 0x1B)
• Compatibility with gogpu Rust backend
• Struct padding in BindGroupLayout wire structs (sampler, texture, storage)
• PipelineLayout creation in examples (use CreatePipelineLayoutSimple)
• GetModuleHandleW: kernel32.dll instead of user32.dll (all Windows examples)
• Sampler MaxAnisotropy default (wgpu-native requires >= 1)
• Texture SampleCount/MipLevelCount defaults (wgpu-native requires >= 1)
• render_bundle shader: fallback without primitive_index (works on all GPUs)

Update imports in your code:

import (
    "github.com/go-webgpu/webgpu/wgpu"
    "github.com/gogpu/gputypes"  // NEW
)

// Before:
config.Format = wgpu.TextureFormatBGRA8Unorm

// After:
config.Format = gputypes.TextureFormatBGRA8Unorm

• goffi: v0.3.1 → v0.3.3 (PointerType argument passing hotfix)
• golang.org/x/sys: v0.38.0 → v0.39.0

• Critical bug in PointerType argument passing (goffi#4)

• Branch protection enabled for main
• All changes now require Pull Requests
• Updated CONTRIBUTING.md with PR workflow

• WebGPU Instance, Adapter, Device creation
• Buffer creation and management (MapAsync, GetMappedRange, Unmap)
• Texture creation and management (2D, depth, render targets)
• Sampler API with filtering and address modes
• Shader module compilation (WGSL)

• Compute Pipeline with workgroups
• Render Pipeline with vertex/fragment stages
• Pipeline Layout and Bind Group Layout
• Bind Groups for resource binding

• Command Encoder and Queue submission
• Render Pass with color and depth attachments
• Vertex buffers with custom layouts
• Index buffers (Uint16, Uint32)
• Depth buffer support (DepthStencilState)
• MRT (Multiple Render Targets) support
• RenderBundle API for pre-recording render commands

• Instanced rendering (VertexStepModeInstance)
• Indirect drawing (DrawIndirect, DrawIndexedIndirect)
• Indirect compute dispatch (DispatchWorkgroupsIndirect)
• QuerySet API for GPU timestamps
• Error Handling API (PushErrorScope, PopErrorScope)

• Windows support via syscall.LazyDLL
• Linux support via goffi (CGO_ENABLED=0)
• macOS support via goffi (CGO_ENABLED=0)
• Platform-specific Surface creation (HWND, X11, Wayland, Metal)

• Mat4 (4x4 matrix) with Identity, Translate, Scale, Rotate, Perspective, LookAt
• Vec3, Vec4 vector types with common operations

• Triangle (basic rendering)
• Colored triangle (vertex colors)
• Rotating triangle (uniform buffers)
• Textured quad (texture sampling)
• 3D cube (depth buffer, transforms)
• MRT (multiple render targets)
• Compute shader (parallel processing)
• Instanced rendering (25 objects in 1 draw call)
• RenderBundle (pre-recorded commands)
• Timestamp query (GPU timing)
• Error handling (error scopes)

• Zero-CGO architecture using goffi for FFI
• GitHub Actions CI/CD (Linux, macOS, Windows)
• golangci-lint configuration for FFI code
• Pre-release validation script
• Comprehensive test suite (76+ tests)

• github.com/go-webgpu/goffi v0.3.1
• wgpu-native v24.0.3.1