name: auto-animate-optimizer description: Audit and optimize @formkit/auto-animate (FormKit AutoAnimate) usage in React/Vue/web codebases — where the tiny wrapper helps vs hurts (large rendered lists, scroll containers, nested refs, root containers, CSS-measure gotchas), correct imperative API and React hook patterns (enable/disable, durations), WAAPI/exit-animation behavior, and virtualization conflicts. Takes a report-first, approve-before-edit workflow like the other optimizer skills. Use whenever the user mentions auto-animate, @formkit/auto-animate, useAutoAnimate, v-auto-animate, "list animations in React/Vue", or EntAnim issues about auto-animate -- even if they don't say the word "optimize".

AutoAnimate Optimizer

Audit how a codebase uses FormKit AutoAnimate and report what hurts or breaks: it is a ~2KB WAAPI wrapper, so almost all problems are about where it's pointed — huge lists it was never designed to animate, scroll containers, root containers, and anchoring around direct-children and layout-measure assumptions. Report with evidence, agree a plan, only then touch code.

Workflow

1. Scope (quick)

• Find the project root (package.json with @formkit/auto-animate). The lib is framework-agnostic: React (useAutoAnimate), Vue (v-auto-animate directive), and a plain autoAnimate() helper all exist; the audit detects which are in play.
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — finds dependency/auto-animate import mismatch, useAutoAnimate files, list-alabus patterns that are risky (big .map()s under a ref'd parent, nested wrappers, possible scroll containers, inline display: grid), and missing options (duration/easing/enable toggles) worth mentioning.

2. Audit

The script runs for leads, then read the code. Load only what applies:

What the script can't see (you need to eyeball):

• The DOM's timing — the element the ref is on, and whether its direct children are what the user thinks they animate; AutoAnimate's contract is direct children, not all descendants.
• How often children change (data mutations, reorder, virtualization re-mounts?). AutoAnimate reacts to every mutation of direct children — the wrong target means measuring/animating constantly.
• Whether it's worth the animation at all (list protocol animation, or noise the user wants dropped).

Mark findings Confirmed or Suspected exactly like the other optimizer skills.

3. Report

Fill in assets/report-template.md, save as AUTO_ANIMATE_REPORT.md in the project root. Keep it scannable: summary, findings table, per-finding evidence/fix/risk.

4. Plan — stop for approval

Short plan; wait for an explicit "go". Typical ordering:

1. Quick wins — correct hook/directive usage (enable/disable, single ref per parent), removing unused dependency or duplicate wrappers.
2. Structural — remove AutoAnimate from big or virtualized lists (choose: animate λ-summary items, or no animation or CSS-only for the top few), fix scroll-container cases (overflow-y-auto parents or the docs' recommended wrappers), duration/easing polish.
3. Optional — replacing AutoAnimate with vanilla CSS transitions/@starting-style for trivial enter-only cases; grouping nested refs. Each item lists files, expected effect, how to verify, rollback. Let the user drop or reorder.

5. Fix

Only approved items. AutoAnimate edits are almost always small: be surgical, verify in the app (dev or a test page), check that adding and removing the ref still leaves DOM untouched — that is, no leftover position: absolute from an abandoned exit animation (this is the classic "animation broke my render" symptom; see references/misuses.md).

6. Verify and wrap up

• Exercise the enter/update/remove routes in the app; verify smoothness on a long-ish list in DevTools.
• Confirm no leftover absolute positioning, and that animations stop entirely when items are disabled (for an enable toggle).
• List what you couldn't verify at runtime and what's deferred; one suggested next step.

Principles

• Right tool, right size. AutoAnimate is for small direct-child lists; performance problems usually mean the list is too big or dynamic, not the lib. Propose structural fixes, don't blame the 2KB wrapper.
• Direct children only. Point the ref at the true parent of the changing children; nested parents hide repeated measurement and odd behaviors.
• Don't fight virtualization. Virtualized lists mount/unmount constantly — animations re-fire per row on virtualization scroll; AutoAnimate + virtualiz lists in the same tree are an anti-pattern unless carefully segmented.
• Every animation has a reason. AutoAnimate's zero-config is friendly to over-animation; in the report, group animations and cut the ones that don't serve UI clarity (docs' own "do I need animation?" guidance).
• Package cost is uncomplicated; runtime cost is not. The 2KB is never the issue — reflows and layout thrash from measurement are; measure on the real list if the app is slow, don't estimate.