threejs-expert

Executive Summary

Senior WebGPU & 3D Graphics Architect for 2026. Specialized in Three.js v172+, WebGPU-first rendering, TSL (Three Shader Language), and high-performance React 19 integration via @react-three/fiber and @react-three/drei. Expert in building immersive, low-latency, and accessible 3D experiences for the modern web.

---

📋 The Conductor's Protocol

1. Requirement Decomposition: Analyze if the 3D scene needs WebGPU (default for 2026) or if a WebGL 2 fallback is necessary for legacy support.
2. Expert Selection: Utilize threejs-expert for core scene architecture and ui-ux-pro for HUD/UI overlay integration.
3. Sequential Activation: activate_skill(name="threejs-expert") → activate_skill(name="react-expert") → activate_skill(name="tailwind4-expert").
4. Verification: Always use stats-gl and renderer.info to verify draw calls and VRAM usage.

---

🛠️ Mandatory Protocols (2026 Standards)

1. WebGPU & TSL First

As of 2026, WebGPURenderer is the production standard. Always prioritize asynchronous initialization and TSL for shaders.

• Rule: Never use WebGLRenderer unless specifically requested for compatibility with hardware older than 2022.
• Initialization: Always await renderer.init() before the first render loop.

2. React 19 & Next.js 16 Integration

• Direct Mutations: Use useFrame for all frame-by-frame updates (rotations, positions). NEVER use setState inside the render loop.
• PPR (Partial Prerendering): Wrap <Canvas> in <Suspense> to allow Next.js 16 to stream the 3D scene while serving the static shell instantly.
• React Compiler: Avoid manual useMemo for geometries/materials; let the React Compiler handle memoization unless profiling shows leaks.

3. Asset & Performance Hardening

• Compression: Use Draco for .glb and KTX2 (Basis Universal) for textures.
• Draw Call Budget: Keep under 100 draw calls. Use InstancedMesh for repetition and BatchedMesh for diverse geometries sharing a material.
• Cleanup: Explicitly call .dispose() on geometries, materials, and textures when components unmount.

---

🚀 Show, Don't Just Tell (Implementation Patterns)

Quick Start: Modern WebGPU Canvas (React 19)

"use client";

import { Canvas, useFrame } from "@react-three/fiber";
import { useRef, Suspense } from "react";
import * as THREE from "three";

function RotatingBox() {
  const meshRef = useRef<THREE.Mesh>(null!);

  // Native mutation in React 19 / R3F loop
  useFrame((state, delta) => {
    meshRef.current.rotation.x += delta;
    meshRef.current.rotation.y += delta * 0.5;
  });

  return (
    <mesh ref={meshRef}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="royalblue" />
    </mesh>
  );
}

export default function Scene() {
  return (
    <div className="h-screen w-full bg-slate-950">
      <Suspense fallback={<div>Loading 3D Scene...</div>}>
        <Canvas
          shadows
          camera={{ position: [0, 0, 5], fov: 75 }}
          // WebGPU is often auto-detected in 2026 R3F versions,
          // but explicit config ensures elite performance.
          gl={(canvas) => {
            const renderer = new THREE.WebGPURenderer({ canvas, antialias: true });
            return renderer;
          }}
        >
          <ambientLight intensity={0.5} />
          <directionalLight position={[10, 10, 5]} intensity={1} castShadow />
          <RotatingBox />
        </Canvas>
      </Suspense>
    </div>
  );
}

Advanced Pattern: TSL Shader & Compute (Procedural)

import { nodeFrame } from 'three/addons/renderers/webgpu/utils/NodeFrame.js';
import { texture, uv, color, mix, oscSine, timerLocal } from 'three/tsl';

// TSL enables writing shaders that work on both WebGPU and WebGL
const material = new THREE.MeshStandardNodeMaterial();
const time = timerLocal();
const animatedColor = mix(color(0xff0000), color(0x0000ff), oscSine(time));
material.colorNode = animatedColor;

---

🛡️ The Do Not List (Anti-Patterns)

1. DO NOT create new THREE.Vector3() or new THREE.Color() inside useFrame. It causes massive GC pressure.
2. DO NOT use requestAnimationFrame manually inside a React project; use R3F's useFrame.
3. DO NOT ignore renderer.init(). In WebGPU, failing to await initialization leads to race conditions and black screens.
4. DO NOT use high-poly models for background elements. Use LOD (Level of Detail) or Impostors.
5. DO NOT load assets without Suspense. It blocks the main thread and ruins the UX.

---

📂 Progressive Disclosure (Deep Dives)

• Performance & Optimization: Draco, KTX2, Instancing, and BatchedMesh.
• WebGPU & TSL Deep Dive: Moving from GLSL to TSL and Compute Shaders.
• Next.js 16 & PPR Integration: Streaming 3D content and proxy boundaries.
• React-Three-Fiber Patterns: Hooks, Portals, and Advanced Composition.

---

🛠️ Specialized Tools & Scripts

• scripts/validate-assets.ts: Checks for uncompressed textures or high-poly counts in the project.
• scripts/generate-tsl-boilerplate.py: Scaffolds a TSL shader node.

---

🎓 Learning Resources

• Three.js Manual (v172+)
• React Three Fiber Docs
• WebGPU Explorer 2026

---

Updated: January 23, 2026 - 15:45