name: r3f-optimizer description: Audit and optimize React Three Fiber (@react-three/fiber + three + drei) usage — three.js bundle loading and lazy mounting of <Canvas>, frameloop control (always vs demand, invalidate), useFrame hygiene (no allocations per frame, shared vectors), instancing/draw-call reduction, texture and GLTF asset budget (KTX2/Draco compression, VRAM, memory pressure on mobile), dispose/cleanup and context-limit handling, shadows settings, and WebGL a11y (reduced motion, labels, fallbacks). Takes the same report-first, plan-approved workflow. Use when the user mentions react-three-fiber, R3F, @react-three/drei, WebGL performance, "slow/janky 3D scene", high device temperature on mobile 3D, texture/VRAM spikes, or three.js in React/Next.js pages -- even if they don't say "optimize".

React Three Fiber Optimizer

Audit how a codebase uses React Three Fiber (R3F) and tell them what's slow. R3F is a React renderer over three.js's own WebGL canvas, so the problem space is: the three.js bundle (big), a render loop that defaults to 60fps forever, draw calls and VRAM from textures and geometries, and mounting cost from large GLTF files. Report first; plan, approved, fix. For Next.js-specific details pair this skill with the nextjs one (same repo family) — the move here is always: measure, then fix.

Workflow

1. Scope (quick)

• Find the project root (package.json with @react-three/fiber; record three, @react-three/drei, any loaders).
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — finds where <Canvas mounts (statically imported into route/hero files vs lazily), frameloop usage, useFrame hygiene, per-frame allocations, mesh density, Environment/texture loading, missing Suspense/dispose, reduced-motion coverage, and multi-canvas context budget leads.

2. Audit

Confirm the script's leads by reading scene code. Load areas as fit:

Measure the interesting things — don't guess them:

• Scene graph size (r3f inspector, devtools): number of nodes, materials, textures.
• Real fps / jank: Chrome tracing or r3f's stats mode during interaction; record before/after.
• Mobile: DevTools throttling or a device check — mobile GPU is usually the binding constraint.
• Memory: performance.memory, renderer.info (three) — info.memory.textures/geometries is a direct count you can log.

Mark findings Confirmed (seen in code/measurements) or Suspected (needs a run to verify, e.g. a texture size deduces to look from an unproven path).

3. Report

Fill in assets/report-template.md, save as R3F_REPORT.md in the project root. Group by: bundle/load, render loop/GPU, assets/VRAM, a11y/fallbacks.

4. Plan — stop for approval

1. Quick wins — dynamic import the page's <Canvas>; cap dpr and antialias; add frameloop="demand" (+ invalidate()) where the scene is mostly static; drop unneeded drei helpers; remove per-frame allocations.
2. Structural — instancing/merging for many-mesh scenes; texture pipeline (smaller sizes, KTX2/Basis, Draco/meshopt GLTFs); dispose cleanup; mount-on-view gating; shadow configuration (cap shadow map size, casters limited).
3. Optional / design calls — fewer live canvases; an a11y fallback (static image or poster) and prefers-reduced-motion handling (pause frameloop); mobile-first asset budget. Per step: files, expected effect (bundle bytes, fps, memory), verification, rollback. Let the user drop/reorder.

5. Fix

Only approved items. R3F geometry/material/texture changes are behavior-visible — verify one change per group (build/typecheck, run the page, watch animations and useFrame ordering). For asset re-encodes, note the trade-off: compressed formats (KTX2/Basis) shift decode cost to upload-time and keep GPU sampling cheap; uncompressed PNG/JPG textures cost VRAM and bandwidth every load.

6. Verify and wrap up

• Re-measure: bundle (route analysis or next build output), frame cost (traces with the same settings), memory before/after; report deltas or the honest "couldn't measure" statement.
• Verify motions still land (interactions, camera moves, animation events); reduced-motion and fallback behavior still hold.
• Deferred items + next suggested step.

Principles

• Default is expensive. R3F's default canvas render is 60fps continuous with a full renderer; a scene that's not interactive doesn't need that — frameloop="demand" and invalidate() are the first lever.
• Bundle starts where three starts. three.js is large; load it as late as is honest, and don't put an un-gated <Canvas> at the top of a route file (the audit flags statically-imported canvases in route/hero files).
• Draw calls and VRAM, not just "shaders". Many meshes and big uncompressed textures are the games' usual hits; the fixes in render-loop.md and assets-vram.md are mechanical, not exotic.
• Per-frame code is sacred. No allocations, no closures, no state-change patterns in useFrame; reuse Vector3/matrices; exit early when not visible.
• Screen space beats texture size. Texture size and format decide the memory spend more than any React code; work to bytes: KTX2/Basis, Draco/meshopt, mipmaps, the right sizes per target.
• A 3D scene has a 2D floor. A canvas is invisible to keyboard/screen readers; ship a meaningful fallback (poster image, labels, alt text), and pause/reduce motion on request.
• Contexts are not free. Many <Canvas>s on one page can hit browser WebGL context limits — prefer one canvas + composition, or terminate truly unused ones.
• Never chase shader tricks before basics. Low-hanging: cap DPR, powerPreference, demand loop, texture sizes; exotic GPU pipeline rewrites are last.