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';