wgpu 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65be5bedee12b2389a8bf8fd8ec2dcb883d739852178dda17cae6b682a26663e
-  data.tar.gz: 584a76214478803361befac5011bb22df20034f4b9e18731be6685b69877eabd
+  metadata.gz: c118a2950771b2f34f06fcf4642634e57e8b1de07c26681b81aa94d6a1faaf93
+  data.tar.gz: b4f4cc4e97846d21e74144194f97ede7cb2704725cb5887a885345ceedd1c8f1
 SHA512:
-  metadata.gz: cde23ae0101bf4e385adb161faca1221069ba15b275c066bcc1770aaab5f88e957bcaa7f8fcd06e1e711730fa75908fbee31e31140a06ba53c8acc55f4b634ed
-  data.tar.gz: d2d974230e674a282ca23a790eb16155730f2b5d9e97d0bc4df3c08822e862e0b17874c9c41b80155a5297bbda427c53ac35e77a7b455050ddb8c2da02031498
+  metadata.gz: 5fad367a0475a31c846fa57151a01d6fda7aed9a5592f6167237117da8967df7269a7ac0233059a174be0803794dc844ee4660cd1383ce3fa858009620100036
+  data.tar.gz: 967d67b899a1ca01e5e805407677772aeaec152d72ede7b31746a8baef6d5fa04544863f7d8e70a4bb2804506ccf8fdd58036c5d5a99c49cfe338be73d667504

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 1.2.1 - 2026-07-24
+
+### Added
+
+- Add reusable staging buffers to `Queue#read_buffer` and
+  `Queue#read_texture`, together with a padded texture-readback example and
+  guide.
+- Support WGSL override constants and omitted entry points across compute,
+  vertex, and fragment pipeline stages.
+- Add a pinned wgpu-native v27.0.4.0 header fixture, ABI update tooling, and
+  cross-platform native artifact verification.
+- Complete RBS and YARD coverage for the public API and expand acceptance
+  coverage for typed buffers, descriptors, errors, timeouts, resource
+  lifetimes, and GPU examples.
+
+### Changed
+
+- Centralize native capability metadata and validate enum, callback, struct,
+  and function ABI expectations against the pinned wgpu-native release.
+- Make compute and rendering examples verify their results, and enforce
+  documentation coverage, SDL3-free installation, release checks, and strict
+  lavapipe GPU coverage in CI.
+
+### Fixed
+
+- Retain callbacks, user data, devices, and instances through dependent
+  resource and pending-operation lifetimes, preventing use-after-free crashes
+  after release, garbage collection, or timeout.
+- Reject out-of-bounds mapped ranges and prevent late buffer, queue, shader,
+  and error-scope callbacks from corrupting completed operation state.
+- Preserve row padding and clean up temporary resources during buffer and
+  texture readback, including repeated reads with caller-owned staging buffers.
+- Recover rendering loops from timed-out, outdated, and lost surface frames,
+  report fatal acquisition states explicitly, and release every acquired
+  texture and view.
+- Track adopted native handles in leak diagnostics and keep release operations
+  idempotent across wrapper types.
+- Correct the isolated core-gem dependency path and make Windows native
+  artifact checks independent of shell quoting.
+
 ## 1.2.0 - 2026-07-23
 
 ### Added

data/README.md

@@ -53,6 +53,7 @@ export WGPU_LIB_PATH=/path/to/libwgpu_native.so
 
 ### Basic Setup
 
+<!-- wgpu-example: run; expect: Using: -->
 ```ruby
 require 'wgpu'
 
@@ -62,10 +63,15 @@ device = adapter.request_device
 queue = device.queue
 
 puts "Using: #{adapter.info[:device]} (#{adapter.info[:backend_type]})"
+
+device.release
+adapter.release
+instance.release
 ```
 
 ### Compute Shader Example
 
+<!-- wgpu-example: run; expect: [0.0, 2.0, 4.0 -->
 ```ruby
 require 'wgpu'
 
@@ -118,14 +124,23 @@ pass.set_pipeline(pipeline)
 pass.set_bind_group(0, bind_group)
 pass.dispatch_workgroups(input_data.size / 64)
 pass.end_pass
-queue.submit([encoder.finish])
+command_buffer = encoder.finish
+queue.submit(command_buffer)
 
 # Read results
-result = queue.read_buffer(buffer, device: device)
+result = queue.read_buffer(buffer)
 output_data = result.unpack("f*")
 
 puts output_data[0, 10].inspect
 # => [0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0]
+
+[
+  command_buffer, pass, encoder, pipeline, pipeline_layout,
+  bind_group, bind_group_layout, shader, buffer
+].each(&:release)
+device.release
+adapter.release
+instance.release
 ```
 
 ## Examples
@@ -147,6 +162,7 @@ Headless validation examples:
 - `13_error_handling.rb` - Typed, labeled validation errors
 - `14_async_map.rb` - Async mapping through a forced GC cycle
 - `15_timestamp_query.rb` - Feature-gated timestamp query resolution
+- `16_texture_readback.rb` - Aligned readback of a 65-pixel-wide texture with reusable staging
 
 Rendering examples (SDL3):
 - `07_triangle.rb` - Basic triangle rendering

data/docs/README.md

@@ -17,6 +17,6 @@
 - [Upgrading wgpu-native](upgrading_wgpu_native.md)
 - [Releasing](releasing.md)
 
-Generated API documentation is built with `bundle exec yard doc`. Static API
-signatures live in `sig/wgpu.rbs` and validate with
+The published [API reference](https://www.rubydoc.info/gems/wgpu) is generated
+with `bundle exec yard doc`. Static API signatures live in `sig/wgpu.rbs` and validate with
 `bundle exec rbs -I sig validate`.

data/docs/api_coverage.md

@@ -1,6 +1,6 @@
 # WebGPU API coverage
 
-This page records the public Ruby API implemented by wgpu-ruby 1.1 and its
+This page records the public Ruby API implemented by wgpu-ruby 1.2 and its
 relationship to the WebGPU object model. It is a baseline, not a claim that
 every WebGPU feature is implemented.
 
@@ -33,12 +33,12 @@ Legend:
 | `GPUCompilationMessage` | `WGPU::CompilationMessage` | ✅ | Message, type, line, column, offset, and length are typed fields. |
 | `GPUComputePassEncoder` | `WGPU::ComputePass` | ✅ | |
 | `GPUComputePipeline` | `WGPU::ComputePipeline` | ✅ | Auto layout and override constants are accepted. |
-| `GPUDevice` | `WGPU::Device` | ◐ | Resource creation, error scopes, polling, features, and limits are exposed; device-lost and uncaptured-error subscriptions are not. |
-| `GPUDeviceLostInfo` | — | ❌ | |
-| `GPUError` | error hashes and `WGPU::Error` subclasses | ◐ | There is no common `GPUError` value object yet. |
+| `GPUDevice` | `WGPU::Device` | ◐ | Resource creation, error scopes, polling, features, limits, device-lost notification, and uncaptured-error subscriptions are exposed. |
+| `GPUDeviceLostInfo` | callback `reason` and `message` | ◐ | `Device#on_device_lost` exposes the native reason and message without a separate wrapper object. |
+| `GPUError` | `WGPU::GPUError` | ✅ | Typed value object with `type`, `message`, `to_h`, and exception conversion. |
 | `GPUExternalTexture` | — | ❌ | Browser video/external-texture import is not exposed. |
-| `GPUInternalError` | — | ❌ | |
-| `GPUOutOfMemoryError` | — | ❌ | |
+| `GPUInternalError` | `WGPU::InternalError` | ◐ | Represented as a Ruby exception converted from `GPUError`. |
+| `GPUOutOfMemoryError` | `WGPU::OutOfMemoryError` | ◐ | Represented as a Ruby exception converted from `GPUError`. |
 | `GPUPipelineError` | `WGPU::PipelineError` | ◐ | Ruby exception exists; native pipeline error data is not a value object. |
 | `GPUPipelineLayout` | `WGPU::PipelineLayout` | ✅ | |
 | `GPUQuerySet` | `WGPU::QuerySet` | ✅ | |
@@ -53,10 +53,10 @@ Legend:
 | `GPUSupportedLimits` | `Hash` | ◐ | Represented as a Ruby hash. |
 | `GPUTexture` | `WGPU::Texture` | ✅ | |
 | `GPUTextureView` | `WGPU::TextureView` | ✅ | |
-| `GPUUncapturedErrorEvent` | — | ❌ | |
-| `GPUValidationError` | class-specific Ruby exceptions | ◐ | Validation errors are translated during resource creation. |
+| `GPUUncapturedErrorEvent` | `Device#on_uncaptured_error` | ◐ | The callback receives `WGPU::GPUError`; there is no DOM event wrapper. |
+| `GPUValidationError` | `WGPU::ValidationError` | ◐ | Validation errors are translated during resource creation and typed error-scope handling. |
 | `WGSLLanguageFeatures` | — | ❌ | |
-| `GPUObjectBase` | `#handle`, labels on descriptors | ◐ | Common released-state behavior is not yet centralized. |
+| `GPUObjectBase` | `WGPU::NativeResource` | ✅ | All native wrappers share `handle`, `label`, `released?`, `use`, `inspect`, idempotent release, and use-after-release guards. |
 | `GPUPipelineBase` | `#get_bind_group_layout` | ✅ | Implemented by compute and render pipelines. |
 | `GPUCommandsMixin` | `WGPU::CommandEncoder` | ✅ | |
 | `GPUDebugCommandsMixin` | encoder/pass debug methods | ✅ | |
@@ -76,19 +76,22 @@ and DOM canvas ownership) are not implemented.
 
 Constructors are omitted where objects are normally returned by another
 wrapper. `handle` readers are listed once here as a common escape hatch for
-native interoperation.
+native interoperation. Every native wrapper also has the common
+`label`, `released?`, `use`, `inspect`, and idempotent `release` methods from
+`WGPU::NativeResource`.
 
 | Ruby class | Public class methods | Public instance methods |
 |---|---|---|
+| `WGPU` | — | module methods `log_level`, `log_level=`, `on_log` |
 | `WGPU::Instance` | — | `request_adapter`, `request_adapter_async`, `enumerate_adapters`, `enumerate_adapters_async`, `process_events`, `get_canvas_context`, `release`, `handle` |
 | `WGPU::Adapter` | `request`, `from_handle` | `request_device`, `request_device_async`, `info`, `name`, `vendor`, `adapter_type`, `backend_type`, `features`, `has_feature?`, `limits`, `summary`, `release`, `handle`, `instance` |
-| `WGPU::Device` | `request` | `queue`, `adapter`, `adapter_info`, `features`, `has_feature?`, `limits`, all `create_*` methods, `push_error_scope`, `pop_error_scope`, `pop_error_scope_async`, `with_error_scope`, `poll`, `destroy`, `release`, `handle` |
+| `WGPU::Device` | `request` | `queue`, `adapter`, `adapter_info`, `features`, `has_feature?`, `limits`, all `create_*` methods, `push_error_scope`, `pop_error_scope`, `pop_error_scope_async`, `pop_error_scope_typed`, `with_error_scope`, `on_uncaptured_error`, `on_device_lost`, `poll`, `destroy`, `release`, `handle` |
 | `WGPU::Queue` | — | `submit`, `write_buffer`, `write_texture`, `read_buffer`, `read_texture`, `on_submitted_work_done`, `on_submitted_work_done_async`, `release`, `handle` |
 | `WGPU::Surface` | `from_metal_layer`, `from_windows_hwnd`, `from_xlib_window`, `from_wayland_surface` | `configure`, `unconfigure`, `current_texture`, `get_current_texture`, `present`, `get_configuration`, `get_preferred_format`, `capabilities`, `release`, `handle` |
 | `WGPU::CanvasContext` | — | `configure`, `unconfigure`, `get_current_texture`, `present`, `get_configuration`, `get_preferred_format`, `set_physical_size`, `physical_size`, `release` |
-| `WGPU::Buffer` | — | `write`, `mapped_range`, `get_mapped_range`, `unmap`, `map_sync`, `map_async`, `read_mapped_data`, `read_mapped`, `write_mapped`, `read_mapped_floats`, `map_state`, `size`, `usage`, `destroy`, `release`, `handle` |
-| `WGPU::BufferMappedRange` | — | `read_bytes`, `write_bytes`, `read_floats`, `write_floats` |
-| `WGPU::Texture` | `from_handle` | `create_view`, `width`, `height`, `depth_or_array_layers`, `size`, `mip_level_count`, `sample_count`, `dimension`, `format`, `usage`, `destroy`, `release`, `handle` |
+| `WGPU::Buffer` | — | `write`, `mapped_range`, `get_mapped_range`, `unmap`, `map_sync`, `map_async`, `read_mapped_data`, `read_mapped`, `write_mapped`, typed `read_mapped_*` methods, `read_mapped_values`, `map_state`, `size`, `usage`, `destroy`, `release`, `handle` |
+| `WGPU::BufferMappedRange` | — | `read`, `write`, `read_bytes`, `write_bytes`, and typed `read_*` / `write_*` methods |
+| `WGPU::Texture` | `from_handle` | `create_view`, `width`, `height`, `depth_or_array_layers`, `size`, `mip_level_count`, `sample_count`, `dimension`, `format`, `usage`, `surface_status`, `destroy`, `release`, `handle` |
 | `WGPU::TextureView` | `from_handle` | `texture`, `size`, `release`, `handle` |
 | `WGPU::Sampler` | — | `release`, `handle` |
 | `WGPU::QuerySet` | — | `count`, `type`, `destroy`, `release`, `handle` |
@@ -105,6 +108,10 @@ native interoperation.
 | `WGPU::RenderBundleEncoder` | — | pipeline/bind-group/buffer setup, draw/debug methods, `finish`, `release`, `handle` |
 | `WGPU::RenderBundle` | — | `release`, `handle` |
 | `WGPU::AsyncTask` | — | `wait`, `value`, `then`, `complete?`, `pending?`, `error` |
+| `WGPU::GPUError` | `from_hash` | `type`, `message`, `exception_class`, `raise!`, `to_h` |
+| `WGPU::CompilationMessage` | — | `type`, `message`, `line_num`/`line`, `line_pos`/`column`, `offset`, `length`, `to_s` |
+| `WGPU::DataTypes` | `pack`, `unpack`, `byte_size`, `to_pointer`, `validate_alignment!` | — |
+| `WGPU::TextureFormat` | `block_size`, `block_dimensions`, `bytes_per_row`, `aligned_bytes_per_row`, `block_info` | — |
 | `WGPU::Window::SDLWindow` | — | `create_surface`, event/key helpers, `drawable_size`, `close` |
 
 ## Examples as executable specifications
@@ -123,9 +130,10 @@ native interoperation.
 | `10_textured_quad.rb` | Texture sampling | texture upload/view, sampler, texture bind group, draw |
 | `11_rotating_cube.rb` | Depth-tested 3D rendering | vertex/index/uniform/depth resources, pipeline, per-frame uniform write, draw |
 | `12_headless_render.rb` | Offscreen triangle and readback | render-to-texture, block render pass, aligned texture readback, pixel assertions |
-| `13_error_handling.rb` | Typed and labeled validation error | `BufferError`, operation/label context |
+| `13_error_handling.rb` | Typed and labeled validation error | `ArgumentError`, operation/label context |
 | `14_async_map.rb` | Async map and callback retention | `map_async`, `AsyncTask`, typed mapped reads, GC stress |
 | `15_timestamp_query.rb` | Feature-gated GPU timestamps | timestamp pass writes, query resolution, u64 readback |
+| `16_texture_readback.rb` | Non-aligned-width texture readback | texture row alignment helpers, caller-owned reusable staging |
 
 When a public API changes, the corresponding example is part of the acceptance
 test surface. Compute and headless examples are automated in GPU CI; SDL

data/docs/async.md

@@ -19,11 +19,21 @@ That release also exports `wgpuBufferGetMapState` as an unimplemented panic
 stub. `Buffer#map_state` is maintained by wgpu-ruby as `:unmapped`,
 `:pending`, or `:mapped` while map operations run.
 
+The exported `wgpuDeviceCreateComputePipelineAsync` and
+`wgpuDeviceCreateRenderPipelineAsync` functions are also panic stubs in
+wgpu-native v27. Pipeline `*_async` methods therefore retain the safe Ruby
+Thread implementation until those native entry points are implemented.
+
 Synchronous adapter/device requests, `Buffer#map_sync`,
 `Device#pop_error_scope`, and `Queue#on_submitted_work_done` accept
 `timeout:` in seconds. The default `nil` preserves the prior unbounded wait.
 Expiry raises `WGPU::TimeoutError`.
 
+`Device.request` can time out only when its adapter is associated with an
+`Instance`. When adopting a native adapter, pass `instance:` to
+`Adapter.from_handle`; without an instance there is no safe event-progress
+boundary for cleaning up a device that completes after timeout.
+
 `*_async` methods return `WGPU::AsyncTask`, a convenience wrapper backed by a
 Ruby Thread. Concurrent operations on the same WebGPU object are not
 guaranteed safe. Prefer synchronous operations or external serialization when

data/docs/command_encoding.md

@@ -22,3 +22,28 @@ call `end_pass` (or `end`) and `release` yourself.
 Only one pass may be active on a command encoder. `CommandEncoder#finish`
 raises `WGPU::CommandError` while a pass is still active instead of handing
 invalid state to wgpu-native. Calling `end_pass` more than once is harmless.
+
+## Queries and debug markers
+
+Pass descriptors accept `timestamp_writes:` with a query set and beginning/end
+indices. Render passes additionally accept `occlusion_query_set:` and expose
+`begin_occlusion_query` / `end_occlusion_query`. Copy completed query values
+into a buffer with `CommandEncoder#resolve_query_set`; timestamp queries
+require the adapter's `:timestamp_query` feature and a device requested with
+that feature.
+
+[`examples/15_timestamp_query.rb`](../examples/15_timestamp_query.rb) shows the
+complete feature-gated timestamp flow, including query resolution and typed
+`u64` readback.
+
+Command encoders, compute/render passes, and render bundle encoders expose
+`push_debug_group`, `pop_debug_group`, and `insert_debug_marker`. Labels are
+forwarded directly to wgpu-native for capture/debugging tools:
+
+```ruby
+encoder.push_debug_group("upload and dispatch")
+encoder.insert_debug_marker("resources ready")
+encoder.pop_debug_group
+```
+
+Debug groups must be balanced before the encoder or pass is finished.

data/docs/getting_started_compute.md

@@ -3,6 +3,7 @@
 Compute workloads need Ruby 3.2+, the `wgpu` gem, and a supported GPU driver.
 They do not need SDL3.
 
+<!-- wgpu-example: run; expect: [2, 4, 6, 8] -->
 ```ruby
 require "wgpu"
 

data/docs/pipeline_descriptors.md

@@ -5,13 +5,13 @@ WebGPU pipeline descriptors. Passing `layout: :auto`, `"auto"`, or `nil` request
 automatic layout inference. A layout object continues to select an explicit
 pipeline layout.
 
-## Default render state
+## Default pipeline state
 
 The wrapper applies the following WebGPU defaults when a field is omitted:
 
 | State | Field | Default |
 |---|---|---|
-| Vertex | `entry_point` | `"main"` |
+| Vertex/fragment/compute | `entry_point` | omitted (`nil`) |
 | Vertex buffer | `step_mode` | `:vertex` |
 | Primitive | `topology` | `:triangle_list` |
 | Primitive | `strip_index_format` | `:undefined` |
@@ -33,6 +33,11 @@ The wrapper applies the following WebGPU defaults when a field is omitted:
 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

@@ -3,7 +3,17 @@
 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.
+`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:
 

data/docs/resource_lifetime.md

@@ -17,6 +17,10 @@ Ruby finalizers.
 - 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:
 
@@ -81,10 +85,20 @@ 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. In the baseline
-implementation cleanup runs from `ensure`, including exceptional paths.
+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

data/docs/texture_readback.md

@@ -17,3 +17,30 @@ depth/stencil copies require an explicit `aspect:`.
 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

@@ -27,6 +27,11 @@ Pass `timeout:` to adapter/device requests, `Buffer#map_sync`,
 `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

data/docs/upgrading_wgpu_native.md

@@ -9,11 +9,23 @@ Use this checklist for each pinned wgpu-native update.
    remains.
 4. Run `bundle exec rake wgpu:clean wgpu:install` on a disposable cache, then
    test an existing legacy cache separately.
-5. Run `bundle exec rake wgpu:verify_abi`. Review every enum addition, removal,
-   and value change against the checksum-pinned `webgpu.h`.
+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. Mark functions optional only when the Ruby
-   API has a valid capability fallback.
+   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.
@@ -23,4 +35,3 @@ Use this checklist for each pinned wgpu-native update.
 
 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/lib/wgpu/async_task.rb

@@ -4,6 +4,8 @@ require "timeout"
 
 module WGPU
   class AsyncTask
+    # Starts a background task that evaluates the given block.
+    # @raise [ArgumentError] if no block is supplied
     def initialize(&block)
       raise ArgumentError, "block is required" unless block
 
@@ -18,12 +20,20 @@ module WGPU
       end
     end
 
+    # Waits until the task finishes.
+    # @param timeout [Numeric, nil] maximum number of seconds to wait
+    # @return [AsyncTask] this task
+    # @raise [Timeout::Error] if the task does not finish in time
     def wait(timeout: nil)
       joined = timeout ? @thread.join(timeout) : @thread.join
       raise Timeout::Error, "async task timeout" unless joined
       self
     end
 
+    # Waits for and returns the task result.
+    # @param timeout [Numeric, nil] maximum number of seconds to wait
+    # @return [Object] block result
+    # @raise [StandardError] re-raises an exception raised by the block
     def value(timeout: nil)
       wait(timeout: timeout)
       raise @error if @error
@@ -31,20 +41,29 @@ module WGPU
       @value
     end
 
+    # Creates a task that transforms this task's result.
+    # @yieldparam value [Object] completed task result
+    # @return [AsyncTask] chained task
     def then(&block)
       AsyncTask.new do
         block.call(value)
       end
     end
 
+    # Reports whether the task has finished.
+    # @return [Boolean]
     def complete?
       !@thread.alive?
     end
 
+    # Reports whether the task is still running.
+    # @return [Boolean]
     def pending?
       @thread.alive?
     end
 
+    # Returns the exception raised by the task, if any.
+    # @return [StandardError, nil]
     def error
       value
       nil

data/lib/wgpu/commands/command_buffer.rb

@@ -4,21 +4,34 @@ module WGPU
   class CommandBuffer
     attr_reader :handle
 
-    def initialize(handle)
+    # Wraps an encoded native command buffer.
+    # @param handle [FFI::Pointer] native command buffer handle
+    # @param device [Device, nil] device whose callbacks the command buffer may use
+    def initialize(handle, device: nil)
       @handle = handle
+      @device = device
       @submitted = false
     end
 
+    # Reports whether this command buffer has been submitted.
+    # @return [Boolean]
     def submitted?
       @submitted
     end
 
+    # Marks this command buffer as submitted.
+    # @raise [CommandError] if it was already submitted
+    # @return [void]
     def mark_submitted!
       raise CommandError, "Command buffer has already been submitted" if @submitted
 
       @submitted = true
     end
 
+    # Releases the native command buffer handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuCommandBufferRelease(@handle)