name: react-spring-optimizer description: Audit and optimize @react-spring/web usage — import targets (@react-spring/web vs old react-spring v8 vs @react-spring/core), springs bound to changing state every render (should be api.start-driven), orphaned useSpringRef (no api.start/useChain — nothing animates), easing without duration (easings only work with duration), useTransition list config (keys, trail, exitBeforeEnter), useChain orchestration (timesteps/timeframe), loop/Infinity springs, config presets (gentle/wobbly/stiff/slow/molasses), and reduced motion via useReducedMotion / Globals.skipAnimation / immediate. Report with evidence and a plan approved before edits. Use when the user mentions react-spring, @react-spring/web, useSpring, useTrail, useTransition, useChain, or spring animations in React/Next.js -- even if they don't say "optimize".

React Spring (@react-spring/web) Optimizer

Audit how a codebase uses react-spring, report what misbehaves or wastes work, agree a plan, then fix. react-spring's failure modes are different from duration-based libraries: the common bugs are springs bound to React state every render (velocity lost, springs restart), ref-driven springs that are never started (nothing animates), easing configs without duration (silently ignored), and event-driven api.start wired through state instead of direct calls. Report first, plan approved, then edit.

Workflow

1. Scope (quick)

• Project root (package.json — which target: @react-spring/web vs the old react-spring (v8) vs direct @react-spring/core; note React major and Next.js presence).
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — inventories hook usage (useSpring/useSprings/useTrail/useTransition/useChain), ref-orphaned springs, state-driven configs, easing/duration mismatches, loops, reduced-motion coverage.

2. Audit

Read what the script flagged. Load references as fit:

Runtime checks you do by hand: interactive controls that drag/flick (does velocity survive re-renders?), dialogs/notifications entering and exiting (does leave run?), chained sequences (order correct, nothing double-runs).

Mark findings Confirmed or Suspected.

3. Report

Fill in assets/report-template.md, save as REACT_SPRING_REPORT.md in the project root. Group: imports, spring wiring, lists/orchestration, a11y.

4. Plan — stop for approval

1. Quick wins — rename old react-spring/core imports to @react-spring/web; add duration next to any easing; start orphaned refs (api.start or useChain); add immediate / useReducedMotion gates on loops.
2. Structural — convert state-driven useSpring({ to: { x: state } }) to effect-driven api.start per event; consolidate per-item useSpring into useSprings where lists scale; fix useTransition key functions; re-order useChain timesteps.
3. Optional — replacing simple springs with CSS transitions where no interruption/drag physics is wanted. Per step: files, expected effect, verification, rollback. Let the user drop or reorder.

5. Fix

Approved items only. Spring behavior changes are visible — verify each group by exercising the animations: hover/click start, mid-flight interruption (retarget mid-spring — the point of springs), enter/exit on lists, chained sequences.

6. Verify and wrap up

• Reduced-motion emulation (DevTools rendering panel) for any loop; confirm immediate-jump lands on the goal value.
• React Profiler on the components that previously re-rendered per frame.
• Deferred items + next step.

Principles

• Springs are event-driven. The api.start() call carries intent; a config bound to state makes every re-render fight the spring's internal state.
• A ref without a start is a dead spring. ref:-configured springs only run when something calls api.start (an event, or useChain).
• easing needs duration. Easings are ignored otherwise; springs interpolate their own way.
• Right hook for the job. Repeated similar items → useSprings; one value chasing an event → useSpring + api; enter/exit lists → useTransition; sequencing → useChain.
• Defaults are tuned, presets exist. Reach for config.gentle/wobbly/stiff/slow/molasses before hand-tweaking; verify the feel, don't cargo-cult numbers.
• Reduced motion via the provided utility. useReducedMotion sets Globals.skipAnimation globally — jump to goal values instead of animating.
• Docs over memory. Fetch current docs (react-spring.dev) before quoting option names in a plan.