webgpu

WebGPU

Writing WebGPU that works on the browsers you ship to, and does not fail silently when it does not. Whether WebGPU is the right fix for a slow page belongs to the spa-performance skill.

WebGPU almost never throws. A bad call returns an invalid object and reports the error later, and a lost device turns every call into a no-op. Wire up error reporting and device loss before anything else, or a black canvas is all you get.

If an engine owns the device, use the engine. In three.js, Babylon.js, or a library like TypeGPU, follow that library's API and its docs. Do not mix raw WebGPU calls into its frame unless it documents a way to. This skill is for code that owns its own device.

Source checks and dates: SOURCES.md.

Procedure

1. Read setup.md. Detect, request only the features and limits the adapter has, and decide the fallback.
2. Add the uncapturederror listener and device.lost handler from errors-and-device-loss.md. Label every object.
3. For multi-pass or compute work, write down each pass first: what it reads, what it writes, and which buffer holds the current data afterwards.
4. Read the resource for the thing you are building.
5. For any struct shared with the CPU, run node scripts/wgsl-layout.mjs <file.wgsl> and use the offsets it prints. Add --uniform for uniform buffers.
6. Check the resource's checklist, then report how far the code was checked, using the levels in debugging-and-testing.md.

navigator.gpu? -> adapter? -> device?  --any no--> fallback, log why
                                 |
                       error listener + device.lost
                                 |
        +------------------------+------------------------+
        |                        |                        |
   draw to canvas           compute only              both
   canvas.md                compute.md                all three
   render-basics.md              |
        |                        |
        +--- buffers-and-textures.md, wgsl.md, pipelines.md ---+
                                 |
          check it: debugging-and-testing.md   slow? profiling.md