performance-optimization

# Performance Optimization Skill ## Context Applies when building performance-sensitive features, optimizing re-renders, reducing draw calls, minimizing bundle size, fixing memory leaks, profiling bottlenecks, or implementing game loops. ## Rules 1. **60 fps target** — 16.67 ms per frame max in game rendering 2. **Minimize re-renders** — `React.memo`, `useMemo`, `useCallback` used deliberately after profiling 3. **Refs for 60 Hz mutations** — never `useState` for per-frame updates 4. **Batch draw calls** — group similar geometries/materials in Three.js 5. **InstancedMesh** for > 10 similar objects (particles, enemies, bullets) 6. **Optimize geometry** — low polycounts; LOD for distant objects; frustum culling 7. **Lazy-load assets** — textures/models/sounds on demand; preload only critical 8. **Code-split** — dynamic `import()` by route/feature; `React.lazy` + `Suspense` 9. **Memoize expensive calculations** — `useMemo` with stable deps 10. **Debounce/throttle** resize, scroll, input handlers 11. **Profile first** — React DevTools Profiler + Chrome Performance + Spector.js before optimizing 12. **Bundle budget** — < 500 KB gzipped initial load (matches `budget.json`) 13. **Tree-shake** — import individual symbols, not whole modules 14. **Audio**: reuse Howler instances; unload unused sounds 15. **Memory**: dispose Three.js resources on unmount; break ref cycles ## Lighthouse Budget (aligned with `budget.json`) | Metric | Target | |---|---| | Performance score | ≥ 90 | | LCP | < 2.5 s | | TTI | < 3.5 s | | CLS | < 0.1 | | Initial JS gzipped | < 500 KB | ## Examples ### ✅ Memoized leaf component ```tsx import { memo, useCallback, useMemo } from 'react'; interface HUDProps { score: number; health: number; onPause: () => void; } function GameHUDInner({ score, health, onPause }: HUDProps): JSX.Element { const healthColor = useMemo(() => (health > 50 ? '#0f0' : '#f00'), [health]); const handlePause = useCallback(() => onPause(), [onPause]); return ( <div className="hud"> <span>Score: {score}</span> <span style={{ color: healthColor }}>Health: {health}%</span> <button onClick={handlePause}>Pause</button> </div> ); } export const GameHUD = memo(GameHUDInner); ``` ### ✅ Ref-based animation — zero re-renders ```tsx import { useRef } from 'react'; import { useFrame } from '@react-three/fiber'; import * as THREE from 'three'; function Spinner(): JSX.Element { const mesh = useRef<THREE.Mesh>(null); useFrame((_, delta) => { if (mesh.current) mesh.current.rotation.y += delta; }); return <mesh ref={mesh}><boxGeometry /><meshStandardMaterial /></mesh>; } ``` ### ✅ Stable references outside render ```tsx const ORIGIN = [0, 0, 0] as const; function At(): JSX.Element { return <mesh position={ORIGIN}><sphereGeometry /></mesh>; } ``` ### ✅ Code-splitting a heavy overlay ```tsx import { lazy, Suspense } from 'react'; const HelpOverlay = lazy(() => import('./HelpOverlay')); function App(): JSX.Element { return ( <Suspense fallback={null}> <HelpOverlay /> </Suspense> ); } ``` ### ❌ Anti-Patterns ```tsx // BAD: useState in useFrame — 60 re-renders/sec useFrame(() => setRotation(r => r + 0.01)); // BAD: new object every render <mesh position={[0, 0, 0]}>…</mesh> // BAD: unmemoized expensive calc inside render const sorted = data.sort((a, b) => a - b); // BAD: importing entire lodash import _ from 'lodash'; // BAD: forgetting to dispose geometry / material / texture ``` ## Profiling Workflow 1. **Measure before** — React Profiler (component renders), Performance panel (frame times), Spector.js (draw calls) 2. **Identify** the hottest component or the longest task 3. **Hypothesize** (re-render? layout thrash? draw calls? allocation?) 4. **Change one thing** and re-measure 5. **Record evidence** in the PR (screenshots, numbers, flamegraphs) ## Memory-Leak Patterns - Forgotten `setInterval` / subscriptions → cleanup in `useEffect` return - Undisposed `THREE.Geometry` / `Material` / `Texture` → dispose on unmount - Global event listeners → `removeEventListener` in cleanup - Closures capturing large data → `useRef` or restructure ## Validation Checklist - [ ] Profile shows no regression (or documented acceptable trade-off) - [ ] No `useState` in `useFrame`; 60 Hz updates use refs - [ ] `InstancedMesh` used for > 10 similar objects - [ ] Three.js resources disposed on unmount - [ ] Bundle within budget (`budget.json`) after changes - [ ] Lighthouse score ≥ 90 for changed paths - [ ] No memory leak in 5-minute soak test (DevTools Memory)