Agent Skills: WebGPU Canvas Development

WebGPU Canvas Development

Production patterns for WebGPU rendering integrated with web components. This skill covers device initialization, buffer management, shader development, and resource lifecycle management.

Related Skills

• web-components: Component lifecycle for WebGPU cleanup, handleEvent pattern
• javascript: Async initialization, AbortController, memory management
• ux-accessibility: Reduced motion, canvas ARIA labels
• ux-animation-motion: Animation timing, frame-rate independence
• ipad-pro-design: Touch interactions, device pixel ratio

WebGPU Browser Support (2025)

| Browser | Status | Notes | |---------|--------|-------| | Chrome 113+ | Full support | Default enabled | | Edge 113+ | Full support | Chromium-based | | Safari 18+ | Full support | macOS/iOS | | Firefox 139+ | Behind flag | Nightly only |

// Feature detection
if (!navigator.gpu) {
  console.warn('WebGPU not supported, falling back to Canvas 2D');
  return;
}

Rule 1: Initialize Once, Reuse Forever

Adapter and device acquisition is expensive. Initialize once at startup, store references.

/**
 * WebGPU singleton for adapter/device management
 *
 * Skills applied:
 * - javascript: Singleton pattern, async initialization
 * - web-components: Integration with component lifecycle
 */
class WebGPUContext {
  static #adapter = null;
  static #device = null;
  static #initialized = false;
  static #initPromise = null;

  static async initialize() {
    // Prevent multiple initialization attempts
    if (this.#initPromise) return this.#initPromise;

    this.#initPromise = this.#doInitialize();
    return this.#initPromise;
  }

  static async #doInitialize() {
    if (this.#initialized) return { adapter: this.#adapter, device: this.#device };

    // Check support
    if (!navigator.gpu) {
      throw new Error('WebGPU not supported in this browser');
    }

    // Request adapter with fallback
    this.#adapter = await navigator.gpu.requestAdapter({
      powerPreference: 'high-performance' // or 'low-power' for battery
    });

    if (!this.#adapter) {
      throw new Error('No WebGPU adapter found');
    }

    // Request device with explicit limits
    this.#device = await this.#adapter.requestDevice({
      requiredFeatures: [],
      requiredLimits: {
        maxBindGroups: 4,
        maxUniformBufferBindingSize: 65536,
        maxStorageBufferBindingSize: 134217728 // 128MB
      }
    });

    // Handle device loss
    this.#device.lost.then((info) => {
      console.error('WebGPU device lost:', info.message);
      this.#initialized = false;
      this.#initPromise = null;

      // Attempt recovery if not destroyed intentionally
      if (info.reason !== 'destroyed') {
        this.initialize();
      }
    });

    this.#initialized = true;
    return { adapter: this.#adapter, device: this.#device };
  }

  static get adapter() { return this.#adapter; }
  static get device() { return this.#device; }
  static get initialized() { return this.#initialized; }
}

export { WebGPUContext };

Why: GPU device creation involves driver communication, memory allocation, and state setup. Multiple devices waste VRAM and cause performance issues.

Rule 2: Configure Canvas Context Correctly

Canvas context configuration determines swap chain format, color space, and presentation mode.

/**
 * Configure WebGPU canvas context
 *
 * @param {HTMLCanvasElement} canvas - Target canvas element
 * @param {GPUDevice} device - WebGPU device
 * @returns {GPUCanvasContext} Configured context
 */
function configureCanvasContext(canvas, device) {
  const context = canvas.getContext('webgpu');

  if (!context) {
    throw new Error('Failed to get WebGPU context from canvas');
  }

  // Get preferred format for this adapter
  const format = navigator.gpu.getPreferredCanvasFormat();

  context.configure({
    device,
    format,
    alphaMode: 'premultiplied', // or 'opaque' if no transparency needed
    colorSpace: 'srgb',         // Standard color space
    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
  });

  return context;
}

// Handle device pixel ratio for crisp rendering
function resizeCanvasToDisplaySize(canvas) {
  const dpr = window.devicePixelRatio || 1;
  const displayWidth = Math.floor(canvas.clientWidth * dpr);
  const displayHeight = Math.floor(canvas.clientHeight * dpr);

  if (canvas.width !== displayWidth || canvas.height !== displayHeight) {
    canvas.width = displayWidth;
    canvas.height = displayHeight;
    return true; // Canvas was resized
  }
  return false;
}

Alpha Mode Selection

| Mode | Use Case | |------|----------| | 'opaque' | Full-screen renders, no transparency | | 'premultiplied' | Compositing with HTML (default) |

Why: Wrong alpha mode causes artifacts when compositing WebGPU content with HTML elements.

Rule 3: Buffer Creation Patterns

Buffers are GPU memory allocations. Choose the right usage flags and update strategy.

Buffer Usage Flags

| Flag | Purpose | |------|---------| | GPUBufferUsage.VERTEX | Vertex data (positions, UVs, normals) | | GPUBufferUsage.INDEX | Index data for indexed drawing | | GPUBufferUsage.UNIFORM | Small, frequently updated data (matrices) | | GPUBufferUsage.STORAGE | Large read/write data (compute, particles) | | GPUBufferUsage.COPY_SRC | Source for copy operations | | GPUBufferUsage.COPY_DST | Destination for writes | | GPUBufferUsage.MAP_READ | CPU-readable (readback) | | GPUBufferUsage.MAP_WRITE | CPU-writable (staging) |

Vertex Buffer

function createVertexBuffer(device, data) {
  const buffer = device.createBuffer({
    size: data.byteLength,
    usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
    mappedAtCreation: true
  });

  // Write data while mapped
  new Float32Array(buffer.getMappedRange()).set(data);
  buffer.unmap();

  return buffer;
}

// Usage
const positions = new Float32Array([
  // Triangle: x, y, z for each vertex
  0.0,  0.5, 0.0,
 -0.5, -0.5, 0.0,
  0.5, -0.5, 0.0
]);

const vertexBuffer = createVertexBuffer(device, positions);

Uniform Buffer

function createUniformBuffer(device, size) {
  return device.createBuffer({
    size: Math.max(size, 16), // Minimum 16 bytes for alignment
    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
  });
}

// Update uniform buffer
function updateUniformBuffer(device, buffer, data) {
  device.queue.writeBuffer(buffer, 0, data);
}

// Usage: MVP matrix (64 bytes = 16 floats)
const uniformBuffer = createUniformBuffer(device, 64);
const mvpMatrix = new Float32Array(16);
// ... compute matrix
updateUniformBuffer(device, uniformBuffer, mvpMatrix);

Storage Buffer (Compute/Particles)

function createStorageBuffer(device, size, initialData = null) {
  const buffer = device.createBuffer({
    size,
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
    mappedAtCreation: !!initialData
  });

  if (initialData) {
    new Float32Array(buffer.getMappedRange()).set(initialData);
    buffer.unmap();
  }

  return buffer;
}

// Particle system: position (vec3) + velocity (vec3) + life (f32) = 7 floats per particle
const PARTICLE_COUNT = 10000;
const PARTICLE_STRIDE = 7 * 4; // 28 bytes
const particleBuffer = createStorageBuffer(device, PARTICLE_COUNT * PARTICLE_STRIDE);

Why: Correct usage flags enable GPU optimizations. Missing COPY_DST prevents updates; missing STORAGE prevents compute access.

Rule 4: WGSL Shader Fundamentals

WGSL (WebGPU Shading Language) is the shader language for WebGPU. Write type-safe, GPU-optimized code.

Basic Vertex Shader

// Uniforms bound to group 0, binding 0
struct Uniforms {
  mvp: mat4x4<f32>,
  time: f32,
}

@group(0) @binding(0) var<uniform> uniforms: Uniforms;

// Vertex input
struct VertexInput {
  @location(0) position: vec3<f32>,
  @location(1) color: vec3<f32>,
}

// Vertex output (to fragment shader)
struct VertexOutput {
  @builtin(position) position: vec4<f32>,
  @location(0) color: vec3<f32>,
}

@vertex
fn vs_main(input: VertexInput) -> VertexOutput {
  var output: VertexOutput;
  output.position = uniforms.mvp * vec4<f32>(input.position, 1.0);
  output.color = input.color;
  return output;
}

Basic Fragment Shader

struct FragmentInput {
  @location(0) color: vec3<f32>,
}

@fragment
fn fs_main(input: FragmentInput) -> @location(0) vec4<f32> {
  return vec4<f32>(input.color, 1.0);
}

Compute Shader (Particle Update)

struct Particle {
  position: vec3<f32>,
  velocity: vec3<f32>,
  life: f32,
}

struct SimParams {
  deltaTime: f32,
  gravity: vec3<f32>,
}

@group(0) @binding(0) var<uniform> params: SimParams;
@group(0) @binding(1) var<storage, read_write> particles: array<Particle>;

@compute @workgroup_size(256)
fn cs_main(@builtin(global_invocation_id) id: vec3<u32>) {
  let index = id.x;

  // Bounds check
  if (index >= arrayLength(&particles)) {
    return;
  }

  var p = particles[index];

  // Skip dead particles
  if (p.life <= 0.0) {
    return;
  }

  // Update physics
  p.velocity += params.gravity * params.deltaTime;
  p.position += p.velocity * params.deltaTime;
  p.life -= params.deltaTime;

  particles[index] = p;
}

WGSL Type Reference

| WGSL Type | Size | Description | |-----------|------|-------------| | f32 | 4 bytes | 32-bit float | | i32 | 4 bytes | 32-bit signed int | | u32 | 4 bytes | 32-bit unsigned int | | vec2<f32> | 8 bytes | 2D float vector | | vec3<f32> | 12 bytes | 3D float vector | | vec4<f32> | 16 bytes | 4D float vector | | mat4x4<f32> | 64 bytes | 4x4 float matrix |

Alignment rules: vec3 aligns to 16 bytes in uniform buffers. Use vec4 or pad manually.

Rule 5: Render Pipeline Creation

Pipelines define the complete render state. Create once, reuse every frame.

async function createRenderPipeline(device, format, shaderCode) {
  const shaderModule = device.createShaderModule({
    code: shaderCode
  });

  // Check for compilation errors
  const compilationInfo = await shaderModule.getCompilationInfo();
  for (const message of compilationInfo.messages) {
    if (message.type === 'error') {
      throw new Error(`Shader error: ${message.message}`);
    }
    console.warn(`Shader ${message.type}: ${message.message}`);
  }

  return device.createRenderPipeline({
    layout: 'auto', // Auto-generate bind group layout
    vertex: {
      module: shaderModule,
      entryPoint: 'vs_main',
      buffers: [
        {
          arrayStride: 24, // 6 floats: position (3) + color (3)
          attributes: [
            { shaderLocation: 0, offset: 0, format: 'float32x3' },  // position
            { shaderLocation: 1, offset: 12, format: 'float32x3' }  // color
          ]
        }
      ]
    },
    fragment: {
      module: shaderModule,
      entryPoint: 'fs_main',
      targets: [{ format }]
    },
    primitive: {
      topology: 'triangle-list',
      cullMode: 'back',
      frontFace: 'ccw'
    },
    depthStencil: {
      format: 'depth24plus',
      depthWriteEnabled: true,
      depthCompare: 'less'
    }
  });
}

Vertex Format Reference

| Format | Components | Bytes | |--------|------------|-------| | 'float32' | 1 | 4 | | 'float32x2' | 2 | 8 | | 'float32x3' | 3 | 12 | | 'float32x4' | 4 | 16 | | 'uint32' | 1 | 4 | | 'sint32' | 1 | 4 | | 'uint8x4' | 4 | 4 | | 'unorm8x4' | 4 | 4 |

Rule 6: Bind Groups and Resources

Bind groups connect shader bindings to actual GPU resources.

function createBindGroup(device, pipeline, uniformBuffer, texture, sampler) {
  return device.createBindGroup({
    layout: pipeline.getBindGroupLayout(0), // Group 0
    entries: [
      {
        binding: 0,
        resource: { buffer: uniformBuffer }
      },
      {
        binding: 1,
        resource: texture.createView()
      },
      {
        binding: 2,
        resource: sampler
      }
    ]
  });
}

// Create sampler
const sampler = device.createSampler({
  magFilter: 'linear',
  minFilter: 'linear',
  mipmapFilter: 'linear',
  addressModeU: 'repeat',
  addressModeV: 'repeat',
  maxAnisotropy: 16
});

Bind Group Layout

For explicit control, define layouts manually:

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
      buffer: { type: 'uniform' }
    },
    {
      binding: 1,
      visibility: GPUShaderStage.FRAGMENT,
      texture: { sampleType: 'float' }
    },
    {
      binding: 2,
      visibility: GPUShaderStage.FRAGMENT,
      sampler: { type: 'filtering' }
    }
  ]
});

const pipelineLayout = device.createPipelineLayout({
  bindGroupLayouts: [bindGroupLayout]
});

Rule 7: Render Pass Encoding

Command encoders record GPU commands. Submit batched commands for efficiency.

function render(device, context, pipeline, vertexBuffer, bindGroup, vertexCount) {
  // Get current swap chain texture
  const textureView = context.getCurrentTexture().createView();

  // Create command encoder
  const commandEncoder = device.createCommandEncoder();

  // Begin render pass
  const renderPass = commandEncoder.beginRenderPass({
    colorAttachments: [{
      view: textureView,
      clearValue: { r: 0.1, g: 0.1, b: 0.15, a: 1.0 },
      loadOp: 'clear',
      storeOp: 'store'
    }],
    depthStencilAttachment: {
      view: depthTextureView,
      depthClearValue: 1.0,
      depthLoadOp: 'clear',
      depthStoreOp: 'store'
    }
  });

  // Set pipeline and resources
  renderPass.setPipeline(pipeline);
  renderPass.setBindGroup(0, bindGroup);
  renderPass.setVertexBuffer(0, vertexBuffer);

  // Draw
  renderPass.draw(vertexCount);

  // End pass
  renderPass.end();

  // Submit commands
  device.queue.submit([commandEncoder.finish()]);
}

Load/Store Operations

| Operation | loadOp | storeOp | Use Case | |-----------|--------|---------|----------| | Clear then render | 'clear' | 'store' | Normal rendering | | Preserve previous | 'load' | 'store' | Multi-pass rendering | | Don't care | 'load' | 'discard' | Depth-only pass |

Rule 8: Compute Shader Dispatch

Compute shaders run parallel workgroups. Calculate dispatch size correctly.

async function createComputePipeline(device, shaderCode) {
  const shaderModule = device.createShaderModule({ code: shaderCode });

  return device.createComputePipeline({
    layout: 'auto',
    compute: {
      module: shaderModule,
      entryPoint: 'cs_main'
    }
  });
}

function dispatchCompute(device, pipeline, bindGroup, workgroupCount) {
  const commandEncoder = device.createCommandEncoder();
  const computePass = commandEncoder.beginComputePass();

  computePass.setPipeline(pipeline);
  computePass.setBindGroup(0, bindGroup);

  // Dispatch workgroups
  computePass.dispatchWorkgroups(
    workgroupCount.x,
    workgroupCount.y || 1,
    workgroupCount.z || 1
  );

  computePass.end();
  device.queue.submit([commandEncoder.finish()]);
}

// Calculate workgroup count
function calculateWorkgroups(itemCount, workgroupSize = 256) {
  return {
    x: Math.ceil(itemCount / workgroupSize),
    y: 1,
    z: 1
  };
}

// Usage: 10000 particles, workgroup size 256
const workgroups = calculateWorkgroups(10000, 256); // { x: 40, y: 1, z: 1 }
dispatchCompute(device, computePipeline, computeBindGroup, workgroups);

Workgroup Size Guidelines

| Use Case | Recommended Size | Notes | |----------|------------------|-------| | 1D data (particles) | 256 | Good occupancy | | 2D data (images) | 16x16 (256) | Cache-friendly | | 3D data (volumes) | 8x8x4 (256) | Balance dimensions |

Rule 9: Texture Creation and Loading

Textures store 2D image data on the GPU.

async function loadTexture(device, url) {
  // Fetch image
  const response = await fetch(url);
  const blob = await response.blob();
  const imageBitmap = await createImageBitmap(blob);

  // Create texture
  const texture = device.createTexture({
    size: [imageBitmap.width, imageBitmap.height, 1],
    format: 'rgba8unorm',
    usage: GPUTextureUsage.TEXTURE_BINDING |
           GPUTextureUsage.COPY_DST |
           GPUTextureUsage.RENDER_ATTACHMENT
  });

  // Copy image to texture
  device.queue.copyExternalImageToTexture(
    { source: imageBitmap },
    { texture },
    [imageBitmap.width, imageBitmap.height]
  );

  return texture;
}

// Create depth texture
function createDepthTexture(device, width, height) {
  return device.createTexture({
    size: [width, height, 1],
    format: 'depth24plus',
    usage: GPUTextureUsage.RENDER_ATTACHMENT
  });
}

Texture Formats

| Format | Use Case | |--------|----------| | 'rgba8unorm' | Standard color textures | | 'rgba8unorm-srgb' | sRGB color textures | | 'depth24plus' | Depth buffer | | 'depth32float' | High-precision depth | | 'r32float' | Single-channel float | | 'rgba16float' | HDR textures | | 'rgba32float' | Compute textures |

Rule 10: Web Component Integration

Integrate WebGPU with web components following project patterns.

/**
 * WebGPU Canvas Component
 *
 * Skills applied:
 * - web-components: No querySelector, handleEvent, cleanup
 * - javascript: Async initialization, AbortController
 * - webgpu-canvas: All rules
 */
class GPUCanvas extends HTMLElement {
  // Direct element references - NO querySelector
  #canvas;
  #device = null;
  #context = null;
  #pipeline = null;
  #animationId = null;
  #resizeObserver = null;
  #lastTime = 0;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // Build DOM imperatively
    const style = document.createElement('style');
    style.textContent = `
      :host {
        display: block;
        contain: strict;
      }
      canvas {
        width: 100%;
        height: 100%;
        display: block;
      }
    `;

    this.#canvas = document.createElement('canvas');
    this.#canvas.setAttribute('part', 'canvas');

    this.shadowRoot.appendChild(style);
    this.shadowRoot.appendChild(this.#canvas);
  }

  async connectedCallback() {
    // Initialize WebGPU
    try {
      const { device } = await WebGPUContext.initialize();
      this.#device = device;
      this.#context = configureCanvasContext(this.#canvas, device);
      await this.#createResources();

      // Observe resize
      this.#resizeObserver = new ResizeObserver(() => this.#handleResize());
      this.#resizeObserver.observe(this);

      // Start render loop
      this.#startRenderLoop();
    } catch (error) {
      console.error('WebGPU initialization failed:', error);
      this.dispatchEvent(new CustomEvent('gpu-error', {
        bubbles: true,
        detail: { error }
      }));
    }
  }

  disconnectedCallback() {
    // Cancel animation loop
    if (this.#animationId) {
      cancelAnimationFrame(this.#animationId);
      this.#animationId = null;
    }

    // Disconnect resize observer
    if (this.#resizeObserver) {
      this.#resizeObserver.disconnect();
      this.#resizeObserver = null;
    }

    // Destroy GPU resources
    this.#destroyResources();
  }

  #handleResize() {
    if (resizeCanvasToDisplaySize(this.#canvas)) {
      this.#recreateDepthTexture();
    }
  }

  async #createResources() {
    // Create pipeline, buffers, etc.
    // Implementation depends on specific use case
  }

  #destroyResources() {
    // Destroy buffers explicitly
    // Note: WebGPU resources are garbage collected, but explicit
    // destruction is good practice for large resources
  }

  #startRenderLoop() {
    const frame = (timestamp) => {
      // Calculate delta time (frame-rate independent)
      const deltaTime = (timestamp - this.#lastTime) / 1000;
      this.#lastTime = timestamp;

      // Render
      this.#render(deltaTime);

      // Request next frame
      this.#animationId = requestAnimationFrame(frame);
    };

    this.#animationId = requestAnimationFrame(frame);
  }

  #render(deltaTime) {
    // Check for reduced motion preference
    const prefersReducedMotion = window.matchMedia(
      '(prefers-reduced-motion: reduce)'
    ).matches;

    // Implement render logic
    // Update uniforms, encode commands, submit
  }

  #recreateDepthTexture() {
    // Recreate depth texture on resize
  }
}

customElements.define('gpu-canvas', GPUCanvas);

Rule 11: Error Handling and Device Recovery

Handle GPU errors gracefully with recovery strategies.

class RobustGPUContext {
  #device = null;
  #onDeviceLost = null;

  async initialize(onDeviceLost) {
    this.#onDeviceLost = onDeviceLost;

    const adapter = await navigator.gpu?.requestAdapter();
    if (!adapter) {
      throw new Error('No WebGPU adapter available');
    }

    this.#device = await adapter.requestDevice();

    // Handle device loss
    this.#device.lost.then(async (info) => {
      console.error(`WebGPU device lost: ${info.reason}`, info.message);

      if (info.reason === 'destroyed') {
        // Intentional destruction, don't recover
        return;
      }

      // Notify and attempt recovery
      this.#onDeviceLost?.(info);

      try {
        await this.initialize(this.#onDeviceLost);
        console.log('WebGPU device recovered');
      } catch (error) {
        console.error('WebGPU recovery failed:', error);
      }
    });

    return this.#device;
  }

  // Validation error handling
  pushErrorScope(filter = 'validation') {
    this.#device.pushErrorScope(filter);
  }

  async popErrorScope() {
    const error = await this.#device.popErrorScope();
    if (error) {
      console.error(`WebGPU ${error.constructor.name}:`, error.message);
    }
    return error;
  }
}

// Usage with error scope
const gpu = new RobustGPUContext();
await gpu.initialize((info) => {
  showUserMessage('Graphics reset, please wait...');
});

gpu.pushErrorScope('validation');
// ... WebGPU operations
const error = await gpu.popErrorScope();
if (error) {
  // Handle validation error
}

Error Types

| Error Type | Cause | Recovery | |------------|-------|----------| | GPUValidationError | Invalid API usage | Fix code, re-run | | GPUOutOfMemoryError | VRAM exhausted | Free resources, retry | | Device lost (destroyed) | Tab closed, context lost | Reinitialize | | Device lost (unknown) | Driver crash, GPU reset | Auto-recover |

Rule 12: Performance Optimization

Optimize for consistent frame times and efficient GPU utilization.

Double/Triple Buffering

class BufferPool {
  #buffers = [];
  #currentIndex = 0;
  #size;

  constructor(device, size, usage, count = 3) {
    this.#size = size;
    for (let i = 0; i < count; i++) {
      this.#buffers.push(device.createBuffer({ size, usage }));
    }
  }

  // Get next buffer (round-robin)
  next() {
    const buffer = this.#buffers[this.#currentIndex];
    this.#currentIndex = (this.#currentIndex + 1) % this.#buffers.length;
    return buffer;
  }
}

// Usage: Triple-buffered uniform updates
const uniformPool = new BufferPool(
  device,
  256,
  GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
  3
);

// Each frame, use next buffer
function updateFrame(data) {
  const buffer = uniformPool.next();
  device.queue.writeBuffer(buffer, 0, data);
  return buffer;
}

Batch Rendering

// Bad: One draw call per object
for (const obj of objects) {
  renderPass.setVertexBuffer(0, obj.buffer);
  renderPass.draw(obj.vertexCount);
}

// Good: Instance rendering
const instanceBuffer = createInstanceBuffer(device, instanceData);
renderPass.setVertexBuffer(0, vertexBuffer);
renderPass.setVertexBuffer(1, instanceBuffer);
renderPass.draw(vertexCount, instanceCount);

Timing Queries (Debug)

async function measureGPUTime(device, commandEncoder, operation) {
  // Check for timestamp query support
  if (!device.features.has('timestamp-query')) {
    operation();
    return null;
  }

  const querySet = device.createQuerySet({
    type: 'timestamp',
    count: 2
  });

  const resolveBuffer = device.createBuffer({
    size: 16,
    usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
  });

  commandEncoder.writeTimestamp(querySet, 0);
  operation();
  commandEncoder.writeTimestamp(querySet, 1);

  commandEncoder.resolveQuerySet(querySet, 0, 2, resolveBuffer, 0);

  // Read back results (requires additional staging buffer)
  // Returns time in nanoseconds
}

Rule 13: Memory Management

Track and limit GPU memory usage to prevent crashes.

class GPUResourceTracker {
  #allocations = new Map();
  #totalBytes = 0;
  #maxBytes;

  constructor(maxBytes = 512 * 1024 * 1024) { // 512MB default limit
    this.#maxBytes = maxBytes;
  }

  track(resource, bytes, label = 'unnamed') {
    if (this.#totalBytes + bytes > this.#maxBytes) {
      console.warn(`GPU memory limit exceeded, cannot allocate ${label}`);
      return false;
    }

    this.#allocations.set(resource, { bytes, label });
    this.#totalBytes += bytes;
    return true;
  }

  release(resource) {
    const allocation = this.#allocations.get(resource);
    if (allocation) {
      this.#totalBytes -= allocation.bytes;
      this.#allocations.delete(resource);
    }
  }

  get used() { return this.#totalBytes; }
  get available() { return this.#maxBytes - this.#totalBytes; }

  report() {
    console.log(`GPU Memory: ${(this.#totalBytes / 1024 / 1024).toFixed(2)} MB used`);
    for (const [resource, info] of this.#allocations) {
      console.log(`  ${info.label}: ${(info.bytes / 1024).toFixed(2)} KB`);
    }
  }
}

Complete Example: Particle System

// particle-system.js
const PARTICLE_SHADER = `
struct Particle {
  position: vec3<f32>,
  velocity: vec3<f32>,
  life: f32,
  _padding: f32, // Align to 32 bytes
}

struct SimParams {
  deltaTime: f32,
  gravity: f32,
  _padding: vec2<f32>,
}

@group(0) @binding(0) var<uniform> params: SimParams;
@group(0) @binding(1) var<storage, read_write> particles: array<Particle>;

@compute @workgroup_size(256)
fn update(@builtin(global_invocation_id) id: vec3<u32>) {
  let idx = id.x;
  if (idx >= arrayLength(&particles)) { return; }

  var p = particles[idx];
  if (p.life <= 0.0) { return; }

  p.velocity.y -= params.gravity * params.deltaTime;
  p.position += p.velocity * params.deltaTime;
  p.life -= params.deltaTime;

  particles[idx] = p;
}
`;

class ParticleSystem extends HTMLElement {
  static PARTICLE_COUNT = 10000;
  static PARTICLE_STRIDE = 32; // 8 floats, aligned

  #canvas;
  #device = null;
  #computePipeline = null;
  #particleBuffer = null;
  #uniformBuffer = null;
  #bindGroup = null;
  #animationId = null;
  #lastTime = 0;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    const style = document.createElement('style');
    style.textContent = `:host { display: block; } canvas { width: 100%; height: 100%; }`;

    this.#canvas = document.createElement('canvas');
    this.shadowRoot.append(style, this.#canvas);
  }

  async connectedCallback() {
    const { device } = await WebGPUContext.initialize();
    this.#device = device;

    await this.#initializeParticles();
    this.#startLoop();
  }

  disconnectedCallback() {
    if (this.#animationId) {
      cancelAnimationFrame(this.#animationId);
    }
  }

  async #initializeParticles() {
    const device = this.#device;

    // Create compute pipeline
    const shaderModule = device.createShaderModule({ code: PARTICLE_SHADER });
    this.#computePipeline = device.createComputePipeline({
      layout: 'auto',
      compute: { module: shaderModule, entryPoint: 'update' }
    });

    // Initialize particle data
    const initialData = new Float32Array(ParticleSystem.PARTICLE_COUNT * 8);
    for (let i = 0; i < ParticleSystem.PARTICLE_COUNT; i++) {
      const offset = i * 8;
      initialData[offset + 0] = (Math.random() - 0.5) * 2; // x
      initialData[offset + 1] = Math.random() * 2;          // y
      initialData[offset + 2] = (Math.random() - 0.5) * 2; // z
      initialData[offset + 3] = (Math.random() - 0.5) * 0.5; // vx
      initialData[offset + 4] = Math.random() * 2;           // vy
      initialData[offset + 5] = (Math.random() - 0.5) * 0.5; // vz
      initialData[offset + 6] = Math.random() * 5 + 2;       // life
      initialData[offset + 7] = 0;                           // padding
    }

    this.#particleBuffer = createStorageBuffer(
      device,
      initialData.byteLength,
      initialData
    );

    this.#uniformBuffer = createUniformBuffer(device, 16);

    this.#bindGroup = device.createBindGroup({
      layout: this.#computePipeline.getBindGroupLayout(0),
      entries: [
        { binding: 0, resource: { buffer: this.#uniformBuffer } },
        { binding: 1, resource: { buffer: this.#particleBuffer } }
      ]
    });
  }

  #startLoop() {
    const frame = (timestamp) => {
      const deltaTime = Math.min((timestamp - this.#lastTime) / 1000, 0.1);
      this.#lastTime = timestamp;

      this.#update(deltaTime);
      this.#animationId = requestAnimationFrame(frame);
    };

    this.#animationId = requestAnimationFrame(frame);
  }

  #update(deltaTime) {
    const device = this.#device;

    // Update uniforms
    const uniforms = new Float32Array([deltaTime, 9.8, 0, 0]);
    device.queue.writeBuffer(this.#uniformBuffer, 0, uniforms);

    // Dispatch compute
    const commandEncoder = device.createCommandEncoder();
    const computePass = commandEncoder.beginComputePass();

    computePass.setPipeline(this.#computePipeline);
    computePass.setBindGroup(0, this.#bindGroup);
    computePass.dispatchWorkgroups(
      Math.ceil(ParticleSystem.PARTICLE_COUNT / 256)
    );

    computePass.end();
    device.queue.submit([commandEncoder.finish()]);
  }
}

customElements.define('particle-system', ParticleSystem);

Checklist

Before shipping WebGPU code:

• [ ] Feature detection with graceful fallback
• [ ] Device/adapter initialized once (singleton)
• [ ] Canvas context configured with correct format and alpha mode
• [ ] Device pixel ratio handled for crisp rendering
• [ ] Resize observer for canvas size changes
• [ ] Render loop uses requestAnimationFrame
• [ ] Frame-rate independent updates (delta time)
• [ ] Device lost handler with recovery
• [ ] Error scopes for validation during development
• [ ] Resources cleaned up in disconnectedCallback
• [ ] Reduced motion preference respected
• [ ] WGSL shaders checked for compilation errors
• [ ] Buffer alignment correct (16 bytes for uniforms)
• [ ] Workgroup sizes optimized for target hardware

Quick Reference

Initialization

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const context = canvas.getContext('webgpu');
context.configure({ device, format: navigator.gpu.getPreferredCanvasFormat() });

Buffer Creation

// Vertex
device.createBuffer({ size, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });

// Uniform
device.createBuffer({ size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });

// Storage (compute)
device.createBuffer({ size, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });

Render Loop

const frame = (timestamp) => {
  const deltaTime = (timestamp - lastTime) / 1000;
  lastTime = timestamp;

  // Update & render
  update(deltaTime);
  render();

  requestAnimationFrame(frame);
};
requestAnimationFrame(frame);

Command Submission

const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({ colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store' }] });
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
pass.setVertexBuffer(0, vertexBuffer);
pass.draw(vertexCount);
pass.end();
device.queue.submit([encoder.finish()]);

Files

This skill integrates with:

• js/utils/webgpu-context.js - Singleton WebGPU context
• css/styles/accessibility.css - Reduced motion tokens
• js/components/ - Web component integration patterns

Project WebGPU Effects

The project includes these ready-to-use WebGPU effect components:

| Component | File | Purpose | |-----------|------|---------| | <magical-motes> | js/components/effects/magical-motes.js | Ambient floating particles | | <ink-trail> | js/components/effects/ink-trail.js | Typing feedback particles | | <particle-burst> | js/components/effects/particle-burst.js | Celebration explosions | | <rank-aura> | js/components/effects/rank-aura.js | Wizard rank orbital glow |

Import all effects:

import '/js/components/effects/index.js';