vgpu

Files (1)

• SKILL.md

SKILL.md (first lines)

# WebGPU Shader & Compute Engine (`vercel-labs/vgpu`)

The house engine for next-generation WebGPU visual effects: typed WGSL shaders, fullscreen ambient mesh backgrounds, interactive fluid ripples, particle simulations, and high-throughput GPU compute.

Integrated from Vercel Labs' [`vercel-labs/vgpu`](https://github.com/vercel-labs/vgpu).

---

## 1. Architectural Role & Distinction

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                      VISUAL FX & GRAPHICS DUAL ENGINE                       │
├─────────────────────────────────────────┬───────────────────────────────────┤
│ 1. WEBGPU SHADER ENGINE (vgpu)          │ 2. 3D SPATIAL SCENES (visual-fx-3d│
├─────────────────────────────────────────┼───────────────────────────────────┤
│ • Fullscreen ambient fluid meshes       │ • Declarative 3D scene graphs     │
│ • Interactive plasma & ripples          │ • glTF / GLB product models       │
│ • Audio-reactive visualizers            │ • Spatial lighting & camera rigs  │
│ • GPU particle simulations              │ • Optical liquid glass refraction │
│ • ~25KB gzipped bundle                  │ • React Three Fiber (R3F) & Drei  │
│ • Zero-GPU headless CI testable         │ • ~250KB+ bundle (spatial engine) │
└─────────────────────────────────────────┴───────────────────────────────────┘
```

> **House Rule:** Use `vgpu` for 2D surface shaders, fluid backdrops, and compute passes. Use `visual-fx-3d` strictly when rendering actual 3D spatial geometry, glTF models, or optical refraction panels.

---

## 2. Installation & Ecosystem

```bash
# Core WebGPU toolkit
npm i vgpu

# Headless adapters for CI/CD tests and server-side execution
npm i -D @vgpu/adapter-mock @vgpu/adapter-node
```

---

## 3. Mobile-First Safety & Graceful Fallback Invariant

> **AVCH-133 Invariant:** WebGPU is supported on modern desktop browsers (Chrome 113+, Edge 113+, Safari 18+) and iOS 18+. Older devices, Safari on iOS $\le 17$, older Android handsets, and default Linux Firefox **do not support WebGPU**.
> 
> ⛔ **NEVER instantiate a WebGPU canvas without guarding `navigator.gpu`.** If `navigator.gpu` is undefined or initialization rejects, you MUST gracefully degrade to a high-performance CSS gradient or static SVG background. Never display a blank rectangle or crash the render tree.

### The Standard Guard Pattern
```tsx
import React, { useEffect, useState } from 'react';

export function useWebGPUSupport(): boolean {
  const [supported, setSupported] = useState<boolean>(false);

  useEffect(() => {
    if (typeof navigator !== 'undefined' && 'gpu' in navigator && navigator.gpu) {
      navigator.gpu.requestAdapter().then((adapter) => {
        setSupported(Boolean(adapter));
      }).catch(() => {
        setSupported(false);
      });
    } else {
      setSupported(false);
    }
  }, []);

  return supported;
}
```

---

## 4. Component Recipe: Fullscreen Fluid Ambient Mesh

A responsive, battery-conscious background mesh using typed WGSL shaders with automatic CSS gradient fallback.

```tsx
'use client';

import React, { useEffect, useRef, useState } from 'react';

const SHADER_WGSL = /* wgsl */ `
struct Uniforms {
  time: f32,
  width: f32,
  height: f32,
  speed: f32,
};

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

struct VertexOutput {
  @builtin(position) position: vec4f,
  @location(0) uv: vec2f,
};

@vertex
fn vs_main(@builtin(vertex_index) vertex_index: u32) -> VertexOutput {
  var pos = array<vec2f, 6>(
    vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0),
    vec2f(-1.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0)
  );
  var out: VertexOutput;
  out.position = vec4f(pos[vertex_index], 0.0, 1.0);
  out.uv = pos[vertex_index] * 0.5 + 0.5;
  return out;
}

@fragment
fn fs_main(in: VertexOutput) -> @location(0) vec4f {
  let uv = in.uv;
  let t = u.time * u.speed * 0.3;
  
  // Ambient fluid sinusoidal harmonic waves
  let wave1 = sin(uv.x * 3.0 + t) * cos(uv.y * 2.0 + t * 0.5);
  let wave2 = cos(uv.x * 2.5 - t * 0.8) * sin(uv.y * 3.5 + t);
  let fluid = (wave1 + wave2) * 0.5 + 0.5;

  let colorA = vec3f(0.04, 0.04, 0.08); // Deep obsidian

From sudomadhatter/design-engineer-skills, MIT.

More from sudomadhatter/design-engineer-skills