Spektral WebGPU Library

The topology resolver paired A/B evidence benchmark compares two different execution paths for computing topology:

1. Legacy renderer path: Uses public defensive pass.getResources() followed by resolveComputePassResources.
2. Renderer-owned static-topology cache: Uses a cached approach.

Benchmark Configuration

• Runtime: v22.21.1
• Execution: Uses 24 independent fresh processes (12 per arm) with balanced, alternating pairs.
• Worker Integrity: Verified via SHA-256 (f3b620c021ee8c1bddf0a204bc86285e0387dc939eab0c4745c73bb24e8a3ba8).
• Scope: This is a local CPU-side topology-resolution benchmark. It does not measure GPU timing or guarantee CI portability.

Success and Regression Contracts

• 32-pass acceptance: Requires the median cached throughput to be $\ge$ 2.0x the legacy throughput.
• Regression Contract: A regression is defined only if all three conditions are met:
  1. The 95% bootstrap CI upper bound is below -10%.
  2. There is an absolute loss above 25,000 frames/s.
  3. The loss is larger than 3x the larger arm's Median Absolute Deviation (MAD).
• Cached steady-state contract: After warmup, there must be zero allocations for plan, entry, read, write, layout-entry, or topology-key.

For GPU compute tasks, use ComputePass (single-dispatch) or PingPongComputePass (iterative simulations).

Declaration

Declare storage buffers in defineMaterial:

{ 
  storageBuffers: { 
    name: { size, type, access? } 
  } 
}

Implementation Rules

• Coordinates: Do not use spektralFragment.uv. Derive normalized coordinates manually from global_invocation_id. For a 2D texture domain:

  let uv = (vec2f(globalId.xy) + vec2f(0.5)) / vec2f(domainSize);

• Bindings: Storage buffers are bound at group(1). Storage textures are bound at group(2).
• Data Flow:
  • Use state.writeStorageBuffer(name, data) in useFrame to upload CPU data.
  • Use state.readStorageBuffer(name) to read GPU results asynchronously (Promise<ArrayBuffer>).
• PingPongComputePass: The resources array must contain exactly one sampled pingPong: 'read' descriptor and one storage-write pingPong: 'write' descriptor, both referencing the same material texture with storage: true.

Spektral provides five distinct benchmark suites to answer different optimization questions. Do not combine numbers from different suites.

Suite Overview

• CPU core: Isolates deterministic CPU hot paths (material resolution, packing, graph planning, scheduler, etc.). Use this when changing material normalization, uniform handling, or resource caches.
• Compute topology paired: Runs legacy defensive resource-copy paths against renderer-owned static-topology caches.
• Browser runtime: Measures browser/runtime behavior (navigation, scheduler/render invocation rates, advance() latency) using Chromium with SwiftShader. Use this when changing lifecycle, scheduling, or adapters.
• Hardware GPU: Exercises WGSL shaders on physical hardware using WebGPU. Measures fragment/compute ALU load, texture filtering, and pipeline compilation.
• Real renderer: Runs the production createRenderer path on a physical GPU, measuring JS submit cost, GPU completion span, and total wall time.

Command Reference

Commands should be run from the repository root. To diagnose a hardware suite in a visible browser, append :headed to the command.

# From repository root
pnpm run perf:spektral:core             # CPU core
pnpm run perf:spektral:compute-topology:paired # Compute topology
pnpm run perf:spektral                    # Browser runtime
pnpm run perf:spektral:gpu               # Hardware GPU
pnpm run perf:spektral:renderer           # Real renderer

# From packages/spektral
pnpm run perf:core
pnpm run perf:runtime
pnpm run perf:gpu
pnpm run perf:renderer

The perf:renderer suite runs the production createRenderer path on a physical GPU. It measures JS submit cost, GPU completion span, and wall time.

Baseline Creation

Baseline creation requires a clean worktree, at least five fresh browser processes, and an explicitly controlled power mode. It is immutable and will not overwrite existing fingerprints.

Comparison

Use perf:spektral:renderer:check to validate performance. The check compares the median of independent run medians and rejects baselines with fewer than five processes or incompatible hardware fingerprints.

Note: There is no GitHub-hosted hardware gate; these checks must run on the reference Apple M4 Pro environment to ensure proper Metal/GPU access.

# Create baseline
SPEKTRAL_PERF_POWER_MODE=ac-high-power pnpm run perf:spektral:renderer:baseline

# Check baseline
pnpm run perf:spektral:renderer:check

When building with Spektral, follow this structured workflow to ensure correct resource management and performance:

1. Classify the request: Determine if your shader is Static (no updates), Animated (uniform updates in useFrame), Interactive (pointer/state-driven), Texture-driven (useTexture), a Post-processing pipeline (ShaderPass/BlitPass/CopyPass), or a Compute shader (ComputePass/PingPongComputePass).
2. Pick layer and adapter:
   • Use framework-specific entrypoints (/svelte, /react, or /vue) for runtime usage.
   • Use core entrypoints (spektral or /core) for framework-independent tooling or low-level integrations.
3. Design material boundary:
   • In the Material: Fragment WGSL source, helper functions, uniform/texture/storage buffer declarations, defines, includes, and color pipeline options.
   • In the Runtime (useFrame): Dynamic updates via state.setUniform(...), state.setTexture(...), state.writeStorageBuffer(...), and state.readStorageBuffer(...).
4. Pick render cadence:
   • always: Continuous animation.
   • on-demand: Renders one frame and sleeps until invalidated. Use autoInvalidate: false + invalidation: { mode: 'on-change', token: ... } for state-driven redraws.
   • manual: Requires explicit advance() calls.
5. Add error strategy: Always wire onError. Keep the default overlay in development unless custom UI is required.
6. Validate: Run pnpm run check, pnpm run test, or pnpm run lint (or scoped versions like pnpm --dir packages/spektral run test).