guidance-webgpu-performance

Optimize WebGPU Performance

Find the limiting resource before changing the renderer. Produce a reproducible diagnosis that separates JavaScript preparation, browser/API submission, data transfer, and GPU execution, then make only changes supported by measurements.

Required context

1. Read the repository AGENTS.md and the affected project's DEVELOPMENT.md.
2. Inspect the render loop, update path, buffer and texture ownership, shader code, and resource lifecycle involved in the representative workload.
3. Before adding or changing a benchmark, inspect the affected package's package.json, local Vitest benchmark configuration, existing *.test.bench.ts files, and any shared configuration they import. Do not assume another project's harness applies unchanged.
4. Read the performance diagnostic playbook when classifying a bottleneck, selecting instrumentation, or proposing an optimization.

Establish the performance question

Define the workload and target before measuring:

• Separate initialization, steady rendering, interactive updates, streaming updates, picking/readback, and cleanup. Do not combine them into one unexplained metric.
• Record object and primitive counts, update frequency and size, draw/pass counts, canvas pixel dimensions, device-pixel ratio, transparency, anti-aliasing, and relevant renderer settings.
• Choose the user-visible metric: frame budget and tail latency, update latency, throughput, startup time, or memory. FPS alone can hide missed frames behind the display's refresh-rate ceiling.
• Preserve correctness and representative visual output. A faster result that omits required work is not an optimization.
• Inspect git status --short and preserve unrelated changes. Record when measurements include a dirty worktree.

Classify before optimizing

Use independent CPU and GPU evidence plus controlled perturbations. Do not infer a GPU bottleneck from low FPS or a CPU bottleneck from a busy render callback alone.