name: threejs-optimizer description: Audit and optimize bare three.js usage (WebGLRenderer, scene/camera, geometry/material/texture lifecycle) — render loop hygiene (one renderer.setAnimationLoop vs scattered requestAnimationFrame, RAF callbacks that never cancel on unmount/hot-reload), dispose() coverage for geometries/materials/textures/renderer (GPU memory leaks, context exhaustion), per-frame allocations (new Vector3/Color inside loop bodies), geometry rebuilds per frame vs setAttribute updates, texture settings (anisotropy, colorSpace, mipmaps), unbounded setPixelRatio, shadow map costs, and old three/examples/jsm import paths. Report with evidence and a plan approved before edits. Use when the user mentions three.js, THREE, WebGLRenderer, renderer.setAnimationLoop, or canvas 3D scenes in vanilla JS/framework components -- even if they don't say "optimize". Not for react-three-fiber (see the react-three-fiber skill).

three.js (vanilla) Optimizer

Audit how a codebase uses three.js, report what leaks or wastes GPU/CPU, agree a plan, then fix. Bare three.js failure modes: render loops created per component (stacked RAF callbacks, hot-reload pile-ups, callbacks that keep running after unmount), missing dispose() for geometries, materials, textures, and the renderer (GPU memory grows until contexts die), per-frame heap allocations, and pixel-ratio/shadow settings tuned for screenshots rather than the web. Report first, plan approved, then edit.

Workflow

1. Scope (quick)

• Project root (package.json — three version; note framework wrappers; this skill is for bare three.js — route react-three-fiber projects to the react-three-fiber skill).
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — inventories renderer creations, loop patterns (requestAnimationFrame vs setAnimationLoop, cancellation), dispose coverage, per-frame allocation candidates, pixel ratio/shadow settings, import paths.

2. Audit

Read what the script flagged. Load references as fit:

Runtime checks you do by hand: memory over time (DevTools performance monitor — GPU/JS heap should stabilize), navigating repeatedly through the page holding the canvas (context loss?), hot-reload loops (multiple scenes?), reduced-motion relevance for background scenes.

Mark findings Confirmed or Suspected.

3. Report

Fill in assets/report-template.md, save as THREEJS_REPORT.md in the project root. Group: loop/lifecycle, resources, per-frame cost.

4. Plan — stop for approval

1. Quick wins — cancel/clean RAF callbacks in unmount/effect cleanup; add renderer.dispose() and resource disposal at teardown; bound setPixelRatio(Math.min(devicePixelRatio, 2)); hoist per-frame new THREE.* allocations.
2. Structural — consolidate to one render loop per canvas (renderer.setAnimationLoop); swap per-frame geometry rebuilds for setAttribute updates with needsUpdate; scope shadows (cast/receive + bounded map size) where used.
3. Optional — texture budget (size/anisotropy/colorSpace), visibility-based pause (skip frames when tab hidden or canvas offscreen). Per step: files, expected effect, verification, rollback. Let the user drop or reorder.

5. Fix

Approved items only. Verify visually scene by scene: identical framing/materials after changes, no z-fighting or lighting shifts from shadow scope changes.

6. Verify and wrap up

• Memory soak: run/teardown repeatedly, watch GPU + JS heap plateau.
• FPS deltas where loop/per-frame changes landed; skipped rendering when hidden.
• Deferred items + next step.

Principles

• One renderer per canvas, one loop per renderer. Additional RAF callbacks should piggyback on the frame loop or be explicitly cancelled, not stack new loops.
• Everything GPU-resident gets disposed. geometry.dispose(), material.dispose(), texture.dispose(), renderer.dispose() when a scene dies; leaking contexts crash sites.
• The loop should allocate nothing per frame. Pre-create vectors/colors/objects, reuse.
• Update attributes, not geometry objects. Per-frame rebuild of BufferGeometry (or new THREE.BufferAttribute) churns upload bandwidth.
• DPR and shadow maps are quality dials, not defaults. Bound pixel ratio, scope shadows.
• Live boundaries matter. Offscreen or hidden canvases shouldn't render at all.
• Docs over memory. three.js releases rename/remove APIs (examples/jsm → three/addons, outputEncoding → outputColorSpace) — check the release notes for the installed version.