wgpu 1.1.0 → 1.2.1

data/docs/getting_started_rendering.md

@@ -0,0 +1,62 @@
+# Getting started: rendering
+
+Rendering adds a window-system integration. The bundled helper uses SDL3, but
+surfaces themselves are independent of SDL and may be created from native
+Metal, Win32, Xlib, or Wayland handles.
+
+Add the optional dependency:
+
+```ruby
+gem "wgpu"
+gem "sdl3", "~> 1.0"
+```
+
+Install the SDL3 system library, then load the helper explicitly:
+
+```ruby
+require "wgpu"
+require "wgpu/window"
+
+window = WGPU::Window::SDLWindow.new(
+  title: "WebGPU",
+  width: 800,
+  height: 600
+)
+instance = WGPU::Instance.new
+surface = window.create_surface(instance)
+adapter = instance.request_adapter(compatible_surface: surface)
+device = adapter.request_device
+
+format = surface.capabilities(adapter).fetch(:formats).first
+width, height = window.drawable_size
+surface.configure(
+  device: device,
+  format: format,
+  width: width,
+  height: height,
+  present_mode: :fifo
+)
+```
+
+For every frame, acquire `surface.current_texture`, create a view, encode and
+submit a render pass, call `surface.present`, and release frame-local objects.
+The returned texture exposes `surface_status` as `:success_optimal` or
+`:success_suboptimal`. Acquisition failures raise
+`WGPU::SurfaceAcquisitionError`; inspect its `status` reader for `:timeout`,
+`:outdated`, `:lost`, `:out_of_memory`, or `:device_lost`. Reconfigure on
+`:outdated`/`:lost` after re-reading the drawable size.
+When `drawable_size` changes, configure the surface again with positive pixel
+dimensions. Do not render while a minimized window reports zero dimensions.
+
+`Surface` is the low-level native-window API. `CanvasContext` owns and
+delegates to a surface while retaining the familiar configure/acquire/present
+shape. Integrations other than SDL3 can pass an `FFI::Pointer` obtained from
+their window toolkit to `Surface.from_metal_layer`,
+`Surface.from_windows_hwnd`, `Surface.from_xlib_window`, or
+`Surface.from_wayland_surface`. The application must keep the corresponding
+native window/display/layer alive longer than the surface; wgpu-ruby does not
+take ownership of those platform objects.
+
+[`examples/09_clear_color.rb`](../examples/09_clear_color.rb) is the smallest
+resizable render loop. The other rendering examples cover vertex/index
+buffers, textures, bind groups, depth testing, and uniform updates.

data/docs/installation.md

@@ -0,0 +1,94 @@
+# Installation and native artifacts
+
+wgpu-ruby is a Ruby-FFI binding. Gem installation downloads a prebuilt
+wgpu-native library; it does not compile a C extension.
+
+## Supported runtime
+
+- Ruby 3.2 or newer
+- 64-bit macOS x86_64/arm64
+- 64-bit Linux glibc x86_64/aarch64
+- 64-bit Windows x86_64 with the MSVC wgpu-native artifact
+
+Linux musl/Alpine and 32-bit runtimes do not have prebuilt artifacts. They may
+still work with a compatible custom library supplied through `WGPU_LIB_PATH`.
+
+## Pinned release and artifacts
+
+The binding targets wgpu-native `v27.0.4.0` from:
+
+`https://github.com/gfx-rs/wgpu-native/releases/download/v27.0.4.0/`
+
+| Ruby platform | Archive | Library |
+|---|---|---|
+| `x86_64-linux` | `wgpu-linux-x86_64-release.zip` | `libwgpu_native.so` |
+| `aarch64-linux` | `wgpu-linux-aarch64-release.zip` | `libwgpu_native.so` |
+| `x86_64-darwin` | `wgpu-macos-x86_64-release.zip` | `libwgpu_native.dylib` |
+| `arm64-darwin` | `wgpu-macos-aarch64-release.zip` | `libwgpu_native.dylib` |
+| Windows `mingw`/`mswin` | `wgpu-windows-x86_64-msvc-release.zip` | `wgpu_native.dll` |
+
+## Resolution order
+
+1. If `WGPU_LIB_PATH` is set, installation skips the download and runtime
+   loading uses that exact file.
+2. Otherwise the runtime uses the first configured cache location:
+   `WGPU_CACHE_DIR`, `XDG_CACHE_HOME`, then the operating-system default.
+3. The legacy `~/.cache/wgpu-ruby/v27.0.4.0/lib/` location is also searched so
+   an existing installation does not require another download.
+4. If the cached library is absent, reinstall the gem or run
+   `bundle exec ruby ext/wgpu/extconf.rb` from a source checkout.
+
+Download uses `curl` when available, then Ruby `Net::HTTP`. Extraction uses
+`rubyzip`, then PowerShell `Expand-Archive` on Windows, then `unzip`.
+
+## Manual installation
+
+1. Download the archive for the target above.
+2. Extract it and locate the library in the archive's `lib` directory.
+3. Set `WGPU_LIB_PATH` to the absolute library path before starting Ruby:
+
+```bash
+export WGPU_LIB_PATH=/opt/wgpu-native/lib/libwgpu_native.so
+bundle exec ruby -Ilib -e 'require "wgpu"; puts WGPU::Native.library_path'
+```
+
+PowerShell:
+
+```powershell
+$env:WGPU_LIB_PATH = "C:\wgpu-native\lib\wgpu_native.dll"
+bundle exec ruby -Ilib -e 'require "wgpu"; puts WGPU::Native.library_path'
+```
+
+The library must match the process architecture and the v27 ABI expected by
+this gem.
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `WGPU_LIB_PATH` | Absolute path to a custom wgpu-native shared library; highest priority. |
+| `WGPU_CACHE_DIR` | wgpu-ruby cache root override. The version directory is created directly beneath it. |
+| `XDG_CACHE_HOME` | Cache base on Unix when `WGPU_CACHE_DIR` is unset. |
+| `WGPU_SKIP_GPU_TESTS=1` | Skip tests that require an adapter. This is a test setting, not a runtime backend selector. |
+
+Default cache paths are:
+
+| Platform | Versioned cache directory |
+|---|---|
+| macOS | `~/Library/Caches/wgpu-ruby/v27.0.4.0/` |
+| Linux/other Unix | `~/.cache/wgpu-ruby/v27.0.4.0/` |
+| Windows | `%LOCALAPPDATA%\wgpu-ruby\v27.0.4.0\` |
+
+Every downloaded archive is checked against the SHA-256 digest recorded in
+`lib/wgpu/native/distribution.rb` before extraction. A mismatch deletes the
+archive and stops installation.
+
+## Troubleshooting
+
+- **Library not found:** rerun the install hook or set `WGPU_LIB_PATH`.
+- **Unsupported platform:** build wgpu-native for the host and use
+  `WGPU_LIB_PATH`.
+- **Linux cannot create an adapter:** install a Vulkan driver. Mesa lavapipe
+  (`mesa-vulkan-drivers`) is sufficient for software-based tests.
+- **Rendering examples fail to load SDL3:** install the SDL3 system library and
+  the `sdl3` Ruby gem. Compute APIs do not load `wgpu/window`.

data/docs/pipeline_descriptors.md

@@ -0,0 +1,43 @@
+# Pipeline descriptors
+
+`WGPU::ComputePipeline` and `WGPU::RenderPipeline` accept Ruby Hashes that mirror
+WebGPU pipeline descriptors. Passing `layout: :auto`, `"auto"`, or `nil` requests
+automatic layout inference. A layout object continues to select an explicit
+pipeline layout.
+
+## Default pipeline state
+
+The wrapper applies the following WebGPU defaults when a field is omitted:
+
+| State | Field | Default |
+|---|---|---|
+| Vertex/fragment/compute | `entry_point` | omitted (`nil`) |
+| Vertex buffer | `step_mode` | `:vertex` |
+| Primitive | `topology` | `:triangle_list` |
+| Primitive | `strip_index_format` | `:undefined` |
+| Primitive | `front_face` | `:ccw` |
+| Primitive | `cull_mode` | `:none` |
+| Primitive | `unclipped_depth` | `false` |
+| Multisample | `count` | `1` |
+| Multisample | `mask` | `0xFFFFFFFF` |
+| Multisample | `alpha_to_coverage_enabled` | `false` |
+| Depth/stencil | `depth_compare` | `:always` |
+| Stencil face | operations | `:keep` |
+| Color target | `write_mask` | `:all` |
+| Blend component | `operation` | `:add` |
+| Blend component | `src_factor` | `:one` |
+| Blend component | `dst_factor` | `:zero` |
+
+`vertex[:module]`, each vertex attribute's `format`, `offset`, and
+`shader_location`, and each color target's `format` are required. A
+depth/stencil state requires `format`. Unknown descriptor keys produce a warning
+so misspellings are visible while preserving v1.x compatibility.
+
+When `entry_point` is omitted, the wrapper passes WebGPU's nullable string
+sentinel to wgpu-native. Native pipeline creation then selects the sole matching
+entry point in that shader stage. Specify `entry_point:` when a stage contains
+multiple matching entry points.
+
+Both vertex/fragment and compute stages accept `constants:`, a Hash mapping WGSL
+override names to numeric values. The descriptor keeps all FFI strings and
+arrays alive until native pipeline creation completes.

data/docs/releasing.md

@@ -0,0 +1,32 @@
+# Releasing
+
+The release workflow uses RubyGems Trusted Publishing and runs for `v*` tags.
+Before the first automated release, configure a trusted publisher for the
+`ydah/wgpu-ruby` repository, workflow `release.yml`, and GitHub environment
+`release` on RubyGems.org. The trusted publisher and protected environment are
+repository/RubyGems.org settings, so they cannot be configured or verified from
+this repository alone.
+
+## Dry run
+
+Run the **Push gem** workflow manually from the GitHub Actions page before
+tagging a release. A `workflow_dispatch` run executes the same native build,
+ABI verification, CPU and GPU specs, examples, RuboCop, RBS, YARD, coverage,
+and gem build checks as a tag run. It skips both the tag/version comparison and
+the RubyGems publishing action, so it cannot publish a gem.
+
+Release checklist:
+
+1. Complete the [wgpu-native upgrade checklist](upgrading_wgpu_native.md) when
+   the native version changes.
+2. Update `WGPU::VERSION` and move Unreleased changelog entries under the new
+   version/date heading.
+3. Run the complete local verification documented in the project README.
+4. Build and inspect the gem: `gem build wgpu.gemspec`.
+5. Merge the release commit, create an annotated `vX.Y.Z` tag, and push it.
+6. Confirm CI and the protected `release` environment. The workflow rejects a
+   tag that does not equal `v#{WGPU::VERSION}`.
+7. Verify the published gem and generated documentation on RubyGems.org.
+
+The workflow requests only `contents: write` and `id-token: write`; it stores no
+long-lived RubyGems API key.

data/docs/resource_lifetime.md

@@ -0,0 +1,108 @@
+# Resource lifetime
+
+wgpu-ruby follows wgpu-native's explicit reference-counted handle model.
+Callers own every wrapper returned to them and must call `release` when it is no
+longer needed. The library does not automatically release native handles from
+Ruby finalizers.
+
+## `release` and `destroy`
+
+- `release` gives up the wrapper's native reference. It sets the stored handle
+  to `FFI::Pointer::NULL`; calling `release` again is harmless.
+- `destroy` immediately invalidates the underlying GPU resource contents but
+  does not give up the wrapper's reference. Call `release` after `destroy`.
+- Calling another public native operation after `release` raises
+  `WGPU::ResourceError` before FFI is entered. `handle`, `released?`, `label`,
+  `inspect`, and repeated `release` remain available.
+- Every native wrapper supports `use { |resource| ... }`. It returns the block
+  result and releases the wrapper in `ensure`, including when the block raises.
+  This is Ruby convenience API rather than a WebGPU operation.
+- Device callbacks share a lifetime across the device and every derived native
+  wrapper. Releasing a device before a child does not free callback closures
+  that wgpu-native may still reach; they are freed after the final child
+  wrapper and pending callback operation complete.
+
+For short-lived resources:
+
+```ruby
+bytes = device.create_buffer(
+  size: 256,
+  usage: %i[map_read copy_dst]
+).use do |buffer|
+  # Work with buffer; it is released on every exit path.
+end
+```
+
+## Wrapper matrix
+
+The table covers all 23 native wrapper classes. `BufferMappedRange`,
+`AsyncTask`, and `Window::SDLWindow` are not independent wgpu-native
+reference-counted handles.
+
+| Wrapper | `release` | `destroy` | Ownership note |
+|---|:---:|:---:|---|
+| `Instance` | ✅ | — | Release after all adapters/surfaces derived from it. |
+| `Adapter` | ✅ | — | Returned by instance discovery/request. |
+| `Device` | ✅ | ✅ | `release` also releases the cached queue wrapper first. |
+| `Queue` | ✅ | — | Normally owned through `Device#queue`; device release cascades to it. |
+| `Surface` | ✅ | — | Release after unconfiguring and after current texture work completes. |
+| `CanvasContext` | ✅ | — | Releases its internally created surface. |
+| `Buffer` | ✅ | ✅ | Destroy contents when early reclamation is desired, then release. |
+| `Texture` | ✅ | ✅ | Texture views should be released before their texture. |
+| `TextureView` | ✅ | — | `Texture#from_handle`/view wrappers are caller-owned. |
+| `Sampler` | ✅ | — | |
+| `QuerySet` | ✅ | ✅ | Destroy query storage, then release. The wrapper suppresses v27's aborting native double-removal path. |
+| `ShaderModule` | ✅ | — | |
+| `BindGroupLayout` | ✅ | — | Layouts returned by `get_bind_group_layout` are caller-owned. |
+| `BindGroup` | ✅ | — | |
+| `PipelineLayout` | ✅ | — | |
+| `ComputePipeline` | ✅ | — | |
+| `RenderPipeline` | ✅ | — | |
+| `CommandEncoder` | ✅ | — | Finish before release. |
+| `CommandBuffer` | ✅ | — | Release after submission is no longer needed. |
+| `ComputePass` | ✅ | — | End the pass before finishing its encoder. |
+| `RenderPass` | ✅ | — | End the pass before finishing its encoder. |
+| `RenderBundleEncoder` | ✅ | — | Finish before release. |
+| `RenderBundle` | ✅ | — | |
+
+## Recommended release order
+
+Release in the reverse order of creation:
+
+1. End active compute/render passes.
+2. Finish encoders and submit command buffers.
+3. Release pass encoders, command buffers, and command encoders.
+4. Release bind groups, pipelines/layouts, shader modules, samplers, texture
+   views, buffers, textures, and query sets.
+5. Unconfigure and release surfaces/canvas contexts.
+6. Release the device (which releases its queue), then adapter and instance.
+
+Explicitly synchronize work when the application needs resources to remain
+alive until completion. A `CommandBuffer` is consumed by its first successful
+`Queue#submit`; submitting it again raises `WGPU::CommandError`. Submission
+does not itself release the command buffer or its referenced Ruby wrappers.
+
+## Internal staging resources
+
+`Queue#read_buffer` and `Queue#read_texture` create a temporary staging buffer,
+submit a copy, map and read it, then unmap and release it. Cleanup independently
+attempts to unmap and release the command buffer, encoder, and internal staging
+buffer on every exit path, even when an earlier cleanup operation raises.
+Applications should not attempt to retain or release this internal buffer.
+
+For repeated readbacks, pass a caller-owned `staging:` buffer created by the
+same device. It must be unmapped, have `:map_read` and `:copy_dst` usage, and be
+large enough for the requested byte range (`read_buffer`) or padded copy
+footprint (`read_texture`). The queue unmaps it after each read but never
+releases it, so it can be reused and the caller remains responsible for its
+eventual release. A device-owned queue uses its owning device automatically;
+only queues constructed without an owner require the explicit `device:`
+keyword.
+
+## Leak diagnostics
+
+Set `WGPU_DEBUG_LEAKS=1` before requiring the gem, or set
+`WGPU.debug_leaks = true` before creating resources, to enable warnings.
+Unreleased resources are reported with their wrapper class and label during GC
+or process exit. The detector never releases a native handle; it is diagnostic
+only and is disabled by default.

data/docs/shaders.md

@@ -0,0 +1,32 @@
+# Shader modules and diagnostics
+
+WGSL remains the default input:
+
+```ruby
+shader = device.create_shader_module(code: wgsl, label: "simulation")
+```
+
+Pass `validate: true` to request compilation information immediately when the
+loaded wgpu-native version implements that API. Error messages are raised as
+`WGPU::ShaderError` with the shader label and line/column diagnostics. Without
+this option, creation follows the original lazy validation behavior.
+
+`ShaderModule#get_compilation_info` returns a Hash with `status:` and
+`messages:`. Each message is a `WGPU::CompilationMessage` with `type`,
+`message`, `line_num`/`line`, `line_pos`/`column`, `offset`, and `length`.
+
+wgpu-native v27.0.4.0 exports the compilation-info function as an
+unimplemented panic stub. wgpu-ruby detects that version and raises
+`WGPU::ShaderError` before crossing the native boundary. This guard avoids a
+process abort; diagnostics can be enabled when a future pinned wgpu-native
+release implements the function.
+
+wgpu-native's SPIR-V extension is available explicitly:
+
+```ruby
+shader = device.create_shader_module(spirv: binary_bytes, label: "compute")
+```
+
+SPIR-V input must contain a whole number of 32-bit words. It is a
+wgpu-native extension rather than portable WebGPU API and should be avoided
+when browser portability matters.

data/docs/texture_readback.md

@@ -0,0 +1,46 @@
+# Texture readback
+
+`WGPU::TextureFormat` exposes WebGPU texel-block calculations:
+
+```ruby
+tight = WGPU::TextureFormat.bytes_per_row(width, :rgba8_unorm)
+stride = WGPU::TextureFormat.aligned_bytes_per_row(width, :rgba8_unorm)
+```
+
+`block_size` returns the bytes in one texel block, while `block_dimensions`
+returns its width and height. Compressed BC, ETC2/EAC, and ASTC formats use
+their real block dimensions. Formats whose depth representation is
+implementation-defined do not claim a portable copy footprint. Combined
+depth/stencil copies require an explicit `aspect:`.
+
+`Queue#read_texture` validates that `bytes_per_row` is a multiple of WebGPU's
+256-byte copy alignment and large enough for the requested width and format.
+Use `aligned_bytes_per_row` when the tight row is not already aligned. Automatic
+padding and mipmap generation are intentionally outside this low-level binding.
+
+For example, an `rgba8_unorm` row that is 65 pixels wide contains 260 bytes,
+but its smallest valid readback stride is 512 bytes:
+
+```ruby
+width = 65
+height = 2
+bytes_per_row = WGPU::TextureFormat.aligned_bytes_per_row(width, :rgba8_unorm)
+# => 512
+
+pixels = queue.read_texture(
+  source: { texture: texture },
+  data_layout: { bytes_per_row: bytes_per_row, rows_per_image: height },
+  size: { width: width, height: height }
+)
+```
+
+The returned string includes row padding and has
+`bytes_per_row * rows_per_image * depth_or_array_layers` bytes. Read only the
+tight bytes of each row when processing pixels.
+
+Both `Queue#read_texture` and `Queue#read_buffer` accept an optional `staging:`
+buffer for repeated readbacks. It must be unmapped, belong to the same device,
+be large enough for the full returned string, and include both `:map_read` and
+`:copy_dst` usage. The helper unmaps caller-provided staging after each read but
+does not release it, so the caller can reuse it and remains responsible for
+releasing it. The queue uses its owning device when `device:` is omitted.

data/docs/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+## Native library is not found
+
+Run `bundle exec rake wgpu:install`. The error lists every searched cache path.
+For a custom build, set `WGPU_LIB_PATH` to the shared library file, not its
+directory. See [installation](installation.md).
+
+## Download or checksum fails
+
+The installer deletes an archive whose SHA-256 differs from the pinned release
+metadata. Retry on a trusted network. Do not bypass the checksum; download the
+matching artifact manually and set `WGPU_LIB_PATH` if GitHub Releases is
+unavailable.
+
+## No adapter is available
+
+Update the platform GPU driver. On headless Linux, install Vulkan loader and
+Mesa lavapipe, set `VK_ICD_FILENAMES` to the lavapipe ICD JSON, and inspect
+`vulkaninfo --summary`. `WGPU_BACKEND=vulkan` can make backend selection
+explicit.
+
+## A synchronous operation hangs
+
+Pass `timeout:` to adapter/device requests, `Buffer#map_sync`,
+`Device#pop_error_scope`, or `Queue#on_submitted_work_done`. A timeout raises
+`WGPU::TimeoutError`. In an event loop, regularly call
+`Instance#process_events` or `Device#poll`.
+
+For a native adapter wrapped with `Adapter.from_handle`, provide its
+`instance:` before using `Device.request(timeout: ...)`. Timeout is rejected
+without that instance because a late native completion cannot be cleaned up
+safely.
+
+## Texture readback rejects bytes_per_row
+
+Buffer/texture copy rows must be 256-byte aligned. Calculate the value with
+`WGPU::TextureFormat.aligned_bytes_per_row(width, format)` and account for
+padding when decoding each row.
+
+## SDL3 cannot be loaded
+
+Compute code should only `require "wgpu"`. Rendering code must separately add
+the `sdl3` Ruby gem, install the SDL3 system library, and then require
+`wgpu/window`.
+
+## Diagnosing validation and shader errors
+
+Use `device.on_uncaptured_error`, scoped errors, and labels. Compilation-info
+validation is guarded on pinned wgpu-native v27 because its exported function
+is a panic stub; see [Shaders and diagnostics](shaders.md). Set
+`WGPU_DEBUG_LEAKS=1` in development to warn about wrappers that reach GC or
+process exit without `release`.

data/docs/upgrading_wgpu_native.md

@@ -0,0 +1,37 @@
+# Upgrading wgpu-native
+
+Use this checklist for each pinned wgpu-native update.
+
+1. Update only `WGPU::Native::Distribution::VERSION`.
+2. Obtain the five release artifact names and SHA-256 digests from the official
+   wgpu-native GitHub release. Update `ARTIFACTS`.
+3. Run `rg` for the old version and confirm no second version definition
+   remains.
+4. Run `bundle exec rake wgpu:clean wgpu:install` on a disposable cache, then
+   test an existing legacy cache separately.
+5. Regenerate the repository enum fixture from the installed release header:
+
+   ```console
+   bundle exec ruby script/update_abi_fixture.rb \
+     "$WGPU_CACHE_DIR/<version>/include/webgpu/webgpu.h"
+   ```
+
+   The generated comment records the source SHA-256. For the current
+   `v27.0.4.0` release, `include/webgpu/webgpu.h` is
+   `a6fccf7f9f2fa674d1adfe4f6ea89784a876395b2307bfc2b06f2e77cf6cf356`.
+   Review every enum addition, removal, and value change, then run
+   `bundle exec rake wgpu:verify_abi`.
+6. Compare structs, field offsets, callback signatures, and exported functions.
+   Add ABI specs for changed layouts. Check `include/webgpu/wgpu.h` for native
+   extensions as well. `wgpuGetVersion` encodes `vMAJOR.MINOR.PATCH.BUILD` in
+   four bytes; the verifier compares it with `Distribution::VERSION`. Mark
+   functions optional only when the Ruby API has a valid capability fallback.
+7. Run `bundle exec rspec --tag '~gpu'`, RuboCop, RBS validation, and YARD.
+8. Run every `:gpu` spec and `rake examples:ci` with lavapipe. Run rendering
+   examples on at least one real surface backend.
+9. Build the gem and install it into a clean environment without SDL3.
+10. Record ABI/API changes, platform artifacts, and migration notes in
+    `CHANGELOG.md`.
+
+For a dry run, use a temporary `WGPU_CACHE_DIR` and restore the version/artifact
+edits afterward. Never replace the shared user cache as part of verification.

data/ext/wgpu/extconf.rb

@@ -1,151 +1,19 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "net/http"
-require "uri"
+lib_dir = File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
-WGPU_VERSION = "v27.0.4.0"
-GITHUB_RELEASE_URL = "https://github.com/gfx-rs/wgpu-native/releases/download/#{WGPU_VERSION}"
+require "wgpu/native/installer"
 
-PLATFORM_MAP = {
-  /x86_64-linux/ => { file: "wgpu-linux-x86_64-release.zip", lib: "libwgpu_native.so" },
-  /aarch64-linux/ => { file: "wgpu-linux-aarch64-release.zip", lib: "libwgpu_native.so" },
-  /x86_64-darwin/ => { file: "wgpu-macos-x86_64-release.zip", lib: "libwgpu_native.dylib" },
-  /arm64-darwin/ => { file: "wgpu-macos-aarch64-release.zip", lib: "libwgpu_native.dylib" },
-  /mingw|mswin/ => { file: "wgpu-windows-x86_64-msvc-release.zip", lib: "wgpu_native.dll" }
-}.freeze
-
-def detect_platform
-  PLATFORM_MAP.each do |pattern, info|
-    return info if RUBY_PLATFORM =~ pattern
-  end
-  abort "Unsupported platform: #{RUBY_PLATFORM}\nSupported: #{PLATFORM_MAP.keys.map(&:inspect).join(", ")}"
-end
-
-def cache_dir
-  File.join(Dir.home, ".cache", "wgpu-ruby", WGPU_VERSION)
-end
-
-def windows?
-  RUBY_PLATFORM =~ /mingw|mswin/
-end
-
-def curl_available?
-  if windows?
-    system("where curl >nul 2>&1")
+begin
+  installer = WGPU::Native::Installer.new
+  if ENV["WGPU_LIB_PATH"]
+    puts "Using custom wgpu-native from WGPU_LIB_PATH: #{installer.install}"
   else
-    system("which curl >/dev/null 2>&1")
-  end
-end
-
-def download_with_curl(url, dest)
-  system("curl", "-fsSL", "-o", dest, url)
-end
-
-def download_with_ruby(url, dest, redirects = 5)
-  raise "Too many redirects" if redirects == 0
-
-  uri = URI.parse(url)
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = (uri.scheme == "https")
-  http.open_timeout = 10
-  http.read_timeout = 120
-
-  request = Net::HTTP::Get.new(uri.request_uri)
-
-  http.request(request) do |response|
-    case response
-    when Net::HTTPRedirection
-      download_with_ruby(response["location"], dest, redirects - 1)
-    when Net::HTTPSuccess
-      File.open(dest, "wb") do |file|
-        response.read_body { |chunk| file.write(chunk) }
-      end
-    else
-      return false
-    end
-  end
-  true
-end
-
-def download_file(url, dest)
-  return if curl_available? && download_with_curl(url, dest)
-  return if download_with_ruby(url, dest)
-
-  abort "Download failed: #{url}"
-end
-
-def extract_with_rubyzip(zip_path, dest_dir)
-  require "zip"
-  Zip::File.open(zip_path) do |zip_file|
-    zip_file.each do |entry|
-      dest_path = File.join(dest_dir, entry.name)
-      FileUtils.mkdir_p(File.dirname(dest_path))
-      entry.extract(dest_path) { true }
-    end
-  end
-  true
-rescue LoadError
-  false
-end
-
-def extract_with_powershell(zip_path, dest_dir)
-  return false unless windows?
-
-  system("powershell", "-Command", "Expand-Archive -Force -Path '#{zip_path}' -DestinationPath '#{dest_dir}'")
-end
-
-def extract_with_unzip(zip_path, dest_dir)
-  system("unzip", "-o", "-q", zip_path, "-d", dest_dir)
-end
-
-def extract_zip(zip_path, dest_dir)
-  return if extract_with_rubyzip(zip_path, dest_dir)
-  return if windows? && extract_with_powershell(zip_path, dest_dir)
-  return if extract_with_unzip(zip_path, dest_dir)
-
-  abort "Failed to extract zip. Please install 'rubyzip' gem."
-end
-
-def lib_dir
-  File.join(cache_dir, "lib")
-end
-
-def download_wgpu_native
-  platform = detect_platform
-  lib_path = File.join(lib_dir, platform[:lib])
-
-  if File.exist?(lib_path)
-    puts "wgpu-native already cached at #{lib_path}"
-    return lib_path
+    installer.install
   end
-
-  FileUtils.mkdir_p(cache_dir)
-
-  url = "#{GITHUB_RELEASE_URL}/#{platform[:file]}"
-  zip_path = File.join(cache_dir, platform[:file])
-
-  puts "Downloading wgpu-native #{WGPU_VERSION} from GitHub..."
-  puts "  URL: #{url}"
-  download_file(url, zip_path)
-
-  puts "Extracting to #{cache_dir}..."
-  extract_zip(zip_path, cache_dir)
-
-  FileUtils.rm_f(zip_path)
-
-  unless File.exist?(lib_path)
-    abort "Failed to find #{platform[:lib]} after extraction"
-  end
-
-  puts "wgpu-native installed successfully!"
-  lib_path
-end
-
-if ENV["WGPU_LIB_PATH"]
-  puts "Using custom wgpu-native from WGPU_LIB_PATH: #{ENV["WGPU_LIB_PATH"]}"
-else
-  download_wgpu_native
+rescue WGPU::Native::InstallError => error
+  abort error.message
 end
 
 File.write("Makefile", <<~MAKEFILE)