@mehshekari/gsap-motion 3.2.0 → 3.3.0

package/README.md

@@ -28,7 +28,7 @@ The audit needs no install. Pin the version, so a new rule cannot fail your
 build without warning:
 
 ```json
-"lint": "eslint && npx @mehshekari/gsap-motion@3.2.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.3.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "3.2.0"
+  version: "3.3.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -18,8 +18,8 @@ Core principles:
 
 - **Motion carries meaning or it goes.** Every animation answers "what does
   this tell the visitor?" Hierarchy, causality, continuity, state, or
-  personality. An animation that answers none of those is decoration with a
-  frame cost, and the right move is to delete it.
+  personality. One that answers none of those is decoration with a frame cost:
+  delete it.
 - **A timeline, not a pile of tweens.** Five independent tweens with hand-tuned
   delays is a choreography nobody can change. One timeline with labels and
   relative positions is the same animation you can actually retime.
@@ -33,16 +33,16 @@ Core principles:
 
 ## Setup
 
-1. **Everything is free.** GSAP became 100% free, every former Club plugin
-   included, with 3.13 (April 2025). Check `package.json` for what the project
-   has — `gsap`, and `@gsap/react` for React — before writing imports. Install
-   steps for a membership, a token, an `.npmrc` or `gsap-bonus.tgz` come from
-   stale training data: stop.
+1. **Everything is free.** GSAP became 100% free with 3.13 (April 2025), every
+   former Club plugin included. Check `package.json` for what the project has —
+   `gsap`, and `@gsap/react` for React — before writing imports. Install steps
+   for a membership, a token, an `.npmrc` or `gsap-bonus.tgz` are stale
+   training data: stop.
 2. **Read the project's own animation rules first. They outrank this skill.**
-   Look for `ANIMATION.md` at the repository root, then for a file that
-   `AGENTS.md`, `CLAUDE.md` or similar points to. Open
+   Look for `ANIMATION.md` at the root, then a file `AGENTS.md`, `CLAUDE.md` or
+   similar points to. Open
    [reference/project-rules.md](reference/project-rules.md) only when there is
-   no such file, or for its RTL, colour and waiver rules.
+   none, or for its RTL, colour and waiver rules.
 3. **Load by the size of the request, and nothing "for completeness".**
    - **One element, one tween or interaction** — a hover, a fade, a retime:
      [motion-design.md](reference/motion-design.md) and the command's own
@@ -80,12 +80,11 @@ Core principles:
 Routing:
 
 - **No argument, or no target:** read [routing.md](reference/routing.md) and
-  ask what should move. A whole page or site with nothing in it named — "add
-  some animation to my homepage" — has no target. Never invent one.
-- **An explicit or clearly implied command:** load its reference and follow it.
-- **A description rather than a command** ("make this feel like Apple", "the
-  hero is boring"): that is `animate`. Classify the intent with routing.md's
-  table, then load what that classification needs.
+  ask what should move. "Add some animation to my homepage" names no target:
+  never invent one.
+- **A command, explicit or implied:** load its reference and follow it.
+- **A description** ("make this feel like Apple", "the hero is boring"): that is
+  `animate`. Classify with routing.md's table, then load what that needs.
 - **Two commands fit:** ask once. A scroll-driven text reveal is `scroll` and
   `text` together, not a coin toss.
 
@@ -113,7 +112,8 @@ intent → precedent → targets → trigger → motion language → technique
 8. **Implementation** — typed, cleaned up, responsive.
 9. **Performance** — transform and opacity; measure before defending anything else.
 10. **Accessibility** — the reduced-motion design, focus, keyboard.
-11. **Validate** — the checklist at the end of [motion-design.md](reference/motion-design.md).
+11. **Validate** — [refine.md](reference/refine.md): audit, fix in order,
+    re-run, then the checklist in [motion-design.md](reference/motion-design.md).
 
 ## Output format
 
@@ -126,16 +126,19 @@ For anything beyond a one-line tweak, answer in this shape, each part short:
 - **Implementation** — complete code. Not pseudocode, not an outline.
 - **Usage** — how to mount it.
 - **Notes** — responsive behaviour, reduced motion, cost, dev-only tooling.
+- **Verification** — one line per check with its evidence, and what you did not
+  check. Silence reads as "checked and fine".
 
-When a simpler technique does what the user asked for, **write only the
-simpler one**. Say in Analysis which technique you declined and why, and offer
-the requested version in one sentence; write it only if the user still wants it
-after that. Never quietly substitute, and never ship both.
+When a simpler technique does what was asked, **write only that one**. Say in
+Analysis what you declined and why, and offer the requested version in a
+sentence — write it only if they still want it. Never substitute quietly, and
+never ship both.
 
 ## Reference map
 
 - **Craft and core** — [motion-design](reference/motion-design.md) ·
-  [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md)
+  [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md) ·
+  [devices](reference/devices.md) · [refine](reference/refine.md)
 - **Domains** — [scrolltrigger](reference/scrolltrigger.md) ·
   [svg](reference/svg.md) · [text](reference/text.md) ·
   [interaction](reference/interaction.md) · [flip](reference/flip.md)
@@ -145,7 +148,7 @@ after that. Never quietly substitute, and never ship both.
 - **Constraints** — [performance](reference/performance.md) ·
   [accessibility](reference/accessibility.md) ·
   [project-rules](reference/project-rules.md)
-- **Presets**, starting points to adapt — [reveal](preset/reveal.md) ·
+- **Presets** to adapt — [reveal](preset/reveal.md) ·
   [magnetic](preset/magnetic.md) · [cursor](preset/cursor.md) ·
   [marquee](preset/marquee.md) · [card-stack](preset/card-stack.md) ·
   [loader](preset/loader.md) · [cinematic](preset/cinematic.md) ·
@@ -160,13 +163,12 @@ after that. Never quietly substitute, and never ship both.
 
 ## Tools
 
-Both scripts catch failures that are **silent**. Run them from the project
-root; `<skill-dir>` is where this skill is installed.
+Both scripts catch **silent** failures. Run them from the project root;
+`<skill-dir>` is where this skill is installed.
 
 ```bash
-# Leaks, per-event tweens, layout properties, eased loops, an onComplete that
-# never fires, shared plugin ids, unregistered plugins, dev tooling left in.
-# Exit 1 on an error.
+# Leaks, per-event and per-frame tweens, layout and paint properties, loops,
+# shared plugin ids, unregistered plugins, dev tooling. Exit 1 on an error.
 node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
 node <skill-dir>/scripts/audit-gsap.mjs src --quiet   # errors only
 node <skill-dir>/scripts/audit-gsap.mjs src --json    # machine-readable
@@ -177,10 +179,11 @@ node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
 node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>   # also flag hue literals
 ```
 
-Run `audit-gsap` first in an `audit` and after writing any animation. A false
-finding is a bug in the script, not something to work around.
+Run `audit-gsap` first in an `audit` and after writing any animation — as a
+Claude Code plugin, a hook already runs it on every edit and hands back what it
+finds. A false finding is a bug in the script, not something to work around.
 
 `MotionPathHelper`, `GSDevTools`, `markers: true` and
-`MorphSVGPlugin.findShapeIndex()` are development-only. A static import ships
-whatever `if` surrounds it: import them dynamically behind a `NODE_ENV` check,
-and delete the block once their value is baked in.
+`MorphSVGPlugin.findShapeIndex()` are development-only, and a static import
+ships whatever `if` surrounds it. Import them dynamically behind a `NODE_ENV`
+check, and delete the block once their value is baked in.

package/skill/reference/devices.md

@@ -0,0 +1,110 @@
+# Devices
+
+A width breakpoint is not a device. A 1024px window can be a phone in landscape,
+a tablet with a keyboard, or a desktop browser scaled to half the screen, and
+"mobile" has stood in for all three for so long that most animation ships one
+guess about which it is.
+
+Read three axes instead. They are independent, and each answers a different
+question.
+
+| Axis | Question | Read from |
+|---|---|---|
+| Layout | How much room is there? | the viewport, in `matchMedia` |
+| Input | Can the visitor hover, and how precise are they? | `(hover: hover)`, `(pointer: fine)` |
+| Motion tier | How much motion should run, and can this device run it? | `prefers-reduced-motion`, then capability |
+
+```ts
+const mm = gsap.matchMedia();
+
+mm.add(
+  {
+    wide: "(min-width: 48em)",
+    hoverable: "(hover: hover) and (pointer: fine)",
+    motion: "(prefers-reduced-motion: no-preference)",
+  },
+  (context) => {
+    const { wide, hoverable, motion } = context.conditions;
+    // …one branch, three facts
+  },
+);
+```
+
+`matchMedia` re-runs the body when any condition changes and reverts what the
+previous run created, so a visitor who rotates a phone, plugs in a mouse or
+turns on reduced motion gets the right version without a reload.
+
+## The device changes the technique, never the story
+
+A scene says something — this section arrived, that item is now first, the page
+is loading. That does not change with the screen. What changes is how much
+motion is spent saying it.
+
+So each beat has three versions, and the beat decides which parts of itself are
+device-sensitive:
+
+- **Full** — the designed version.
+- **Light** — the same meaning, less work: a shorter travel, no blur, fewer
+  elements moving, a stagger that runs as one group.
+- **Static** — the end state, set. Still says *what* happened, with no travel.
+
+Only branch the techniques that actually depend on the device. A fade is a fade
+everywhere; a magnetic cursor is not. Writing three whole timelines where one
+beat differs is how a page ends up with two motion languages and one of them
+untested.
+
+## Start safe, then enhance
+
+Begin from the version that works everywhere — the light one — and add to it
+when an axis says there is room. The opposite order ships the expensive version
+to the device least able to run it and then tries to claw it back.
+
+If you measure capability at run time, **downgrade once**. A scene that keeps
+sampling frame rate and flipping between versions spends its budget on the
+flipping, and the visitor sees the page change its mind. Decide early, once, and
+stay there.
+
+Device memory and core count (`navigator.deviceMemory`, `hardwareConcurrency`)
+are hints, not facts: they are absent on some browsers and rounded on others.
+Use them to pick a tier, never to decide whether a thing works.
+
+## Where to read each axis
+
+`prefers-reduced-motion`, `hover` and `pointer` are media queries, so
+`gsap.matchMedia` is the one place to read them — inside the animation's own
+context, where its cleanup already is.
+
+The trap is reading them during render. A server has no viewport and no pointer,
+so anything that branches on them before mount is a hydration mismatch waiting
+to happen. Each adapter says where its own safe point is:
+
+- **React and Next** — in the `useGSAP` body, never in render. See
+  [react.md](../adapter/react.md).
+- **Vue and Nuxt** — in `onMounted`. See [vue.md](../adapter/vue.md).
+- **Svelte** — in `$effect` or `onMount`. See [svelte.md](../adapter/svelte.md).
+- **Astro** — in the component script, which is already browser-only. See
+  [astro.md](../adapter/astro.md).
+- **Vanilla** — wherever you mount. See [vanilla.md](../adapter/vanilla.md).
+
+## What each axis is allowed to change
+
+| Axis | Changes | Does not change |
+|---|---|---|
+| Layout | travel distance, stagger shape, which elements move, pinning | what the scene says |
+| Input | hover effects, cursors, magnetic pulls, drag affordances | entrance and scroll behaviour |
+| Motion tier | travel, loops, parallax, blur and shadow work | the end state the visitor is left in |
+
+A hover effect with no input branch is the common failure: a tap on a touch
+device fires `mouseenter`, nothing fires the leave, and the effect sticks. The
+audit reports that as `ungated-hover`.
+
+## Reduced motion is a tier, not an off switch
+
+The static version still communicates. It sets the end state, keeps the
+hierarchy the motion was carrying — by order, weight or a very short fade — and
+drops travel, loops and parallax. An empty branch is a page that looks broken to
+the people who asked for less motion.
+
+See [accessibility.md](accessibility.md) for what "reduced" means in practice,
+and [performance.md](performance.md) for measuring a tier rather than guessing
+it.

package/skill/reference/motion-design.md

@@ -86,8 +86,8 @@ radiating, start-to-end reads as reading order. In RTL, "reading order" is
 
 ## Overlap
 
-Sequential beats look like a slideshow. Real choreography overlaps, and the
-overlap is where an animation stops feeling like a list of steps.
+Sequential beats look like a slideshow. Overlap is where an animation stops
+feeling like a list of steps.
 
 ```ts
 tl.to(a, { ... })
@@ -105,15 +105,18 @@ finishing.
 - **Weight** — a large or heavy-looking element should move slower and ease
   harder than a small one. Same duration on a hero image and a caption reads as
   a bug.
-- **Anticipation** — a small counter-move before the main one. Costs 80–120ms
-  and makes a gesture feel intentional. Use on one element, not a group.
+- **Anticipation** — a small counter-move before the main one: 80–120ms, on one
+  element, not a group.
 - **Follow-through** — elements should not all stop at once. A 0.05s offset on
-  the last beat is usually the difference between mechanical and alive.
+  the last beat is the difference between mechanical and alive.
 - **Contrast** — fast against slow is what creates emphasis. If everything moves
   at 400ms, nothing is emphasised.
 - **Restraint** — the most premium-feeling motion is usually one or two things
   moving well, not six things moving at all.
 
+Technique is chosen on a ladder — transition, tween, timeline, plugin, scroll
+takeover — in [routing.md](routing.md).
+
 ## Reading a request
 
 | They say | They usually mean |

package/skill/reference/project-rules.md

@@ -17,6 +17,18 @@ Before writing code, look for the project's animation rules, in this order:
 Read the whole file. Where it disagrees with this skill, the project wins. If a
 project rule looks wrong, say so — do not quietly follow the skill instead.
 
+## A motion budget
+
+A page gets busy one reasonable addition at a time. A budget makes the cost
+visible before the tenth one lands: how many groups may move at once, how many
+loops may be visible, how many scroll-bound and pointer effects a viewport
+carries, and which plugins a route may load.
+
+Going over is allowed — with a reason stated in the answer, not by accident.
+Before adding to a route, inventory what it already animates: that is step 2 of
+the pipeline, and it is also how you find the animation this one should replace
+rather than join.
+
 ## Deriving them when there is no file
 
 A few minutes here is cheaper than a page with two motion languages.
@@ -62,6 +74,10 @@ one is short, and each section is an instruction rather than an essay:
 | Stagger | `amount` (a total) or `each` (per item) |
 | Reduced motion | what the reduced branch shows |
 
+## Motion budget
+<!-- Per viewport: groups moving at once, visible loops, scroll-bound effects,
+     pointer effects. Plugins per route. Going over is allowed, with a reason. -->
+
 ## Verify with
 <!-- The commands to run before calling it done. -->
 

package/skill/reference/refine.md

@@ -0,0 +1,84 @@
+# Refining
+
+Writing the animation is the first draft. This is what turns it into something
+worth shipping, and it is mostly checking rather than writing.
+
+```text
+generate → audit → fix → re-run every check → tune → final
+```
+
+The loop matters because the failures this skill exists to catch are silent: the
+code compiles, the page looks right in a demo, and the leak shows up three
+navigations later. Nothing downstream will tell you. So the check is part of
+writing, not something done afterwards if there is time.
+
+## Audit first, and mean it
+
+Run `audit-gsap` on the file you just wrote, before reading it yourself. It
+costs a second, it is deterministic, and it finds the mechanical failures so
+your attention goes to the ones it cannot see.
+
+With the plugin installed, a hook does this automatically after every edit and
+hands the findings back — see the Tools section of SKILL.md. Without it, run the
+script.
+
+A finding you believe is wrong is a bug in the script. Report it; do not work
+around it with a waiver.
+
+## Fix in this order
+
+The order is not taste. A fix further down the list can be undone by a fix
+further up it, so doing them in this order avoids fixing the same thing twice.
+
+1. **Lifecycle and correctness** — does it clean up, does it run once, does it
+   target what you think it targets.
+2. **Accessibility** — the reduced-motion design, focus order, anything the
+   motion hides from a keyboard.
+3. **Performance** — layout and paint properties, per-frame allocation, work
+   that scales with the number of items.
+4. **Composition** — beats, hierarchy, what happens at the same time.
+5. **Rhythm** — durations, eases, overlap. Last, because everything above
+   changes it.
+
+## Verify a claim before you fix
+
+When a fix rests on a claim about how something behaves — "`clearProps` runs
+after the plugin's last write", "this element is the one that moves under
+`fill`" — check it before writing the fix. A minimal reproduction, one variable
+at a time, and read what actually happened in the DOM.
+
+A fix built on a guess usually works by accident, and the comment above it is
+then wrong for everyone who reads it next.
+
+## When to stop
+
+Stop when every check is clean, or after **three rounds**, reporting what is
+left.
+
+Three is not a budget to spend. Most changes are right after one. Stopping on a
+number matters for the case where a fix keeps moving the problem: the third
+round is where you say what is still wrong and why, rather than trying a fourth
+shape of the same idea.
+
+**Leave what works alone.** The loop is for the animation you were asked about.
+Retiming a neighbouring section because you noticed it is churn: it costs review
+attention, it risks a regression nobody asked for, and it is exactly what the
+`outcome-no-churn` eval measures.
+
+**Depth scales with the request.** A hover retime does not need a composition
+pass. A site intro does.
+
+## Report what you checked
+
+The answer's **Verification** section is one line per check, with its evidence:
+
+```text
+Verification
+- audit-gsap: clean (3 warns waived: layout-property on the grid, with reasons)
+- reduced motion: emulated, the static branch sets the end state
+- StrictMode: mounted twice in dev, no doubled tweens
+- not checked: frame cost on a real phone — no device to hand
+```
+
+Say what you did not check, too. "Not checked" is information; silence reads as
+"checked and fine", and that is the one thing it must never mean.

package/skill/reference/routing.md

@@ -47,6 +47,21 @@ the thing you can say in a sentence — "the logo writes itself, then the dot th
 drew it runs off and writes the word" — and every technique either serves that
 sentence or is cut.
 
+## The technique ladder
+
+Start at the bottom, and each rung up says why the one below is not enough:
+
+1. **A CSS transition** — one property, one state change, no sequencing.
+2. **One transform tween** — it needs an ease or a duration CSS cannot say.
+3. **A timeline** — two or more things must be ordered or overlapped.
+4. **A plugin** — the shape needs it: draw, morph, path, split. Its weight ships
+   to every visitor.
+5. **A scroll takeover** — the scroll position *is* the story. It takes the
+   visitor's control of the page, so it needs the strongest reason of all.
+
+Say the rung in Analysis: "a transition would not sequence these, so this is a
+timeline". A plugin named without that sentence is one nobody justified.
+
 ## Load map
 
 The project's own rules come first, then the size tiers in SKILL.md, setup step
@@ -69,6 +84,8 @@ single hover takes [interaction](interaction.md) and nothing else from its row.
 | Three.js / R3F | [three](../adapter/three.md) or [r3f](../adapter/r3f.md), [performance](performance.md) |
 | Audit an existing animation | [performance](performance.md), [accessibility](accessibility.md), this project's adapter |
 | Retime / re-ease | [motion-design](motion-design.md) only |
+| Hover, touch or reduced-motion branching | [devices](devices.md) |
+| Fixing what an audit found | [refine](refine.md) |
 
 Do not load a domain file "for completeness". Loading `adapter/three.md` for a
 button hover is the failure this map exists to prevent.

package/skill/reference/timeline.md

@@ -4,6 +4,46 @@ A timeline is how choreography stays editable. Five tweens with hand-tuned
 delays encode the same animation in a form nobody can retime without redoing
 the arithmetic.
 
+## Scene and beats
+
+A scene is a set of named beats, and each beat is a label in the code. Writing
+the beats down before the tweens is what stops a timeline becoming a pile of
+numbers nobody can change.
+
+Most scenes are four beats or fewer:
+
+| Beat | Says |
+|---|---|
+| Entrance | this arrived |
+| Emphasis | this is the one that matters — **at most one per scene** |
+| Pause | read this before the next thing moves |
+| Exit | this is finished, or making room |
+
+```ts
+const tl = gsap.timeline();
+
+tl.addLabel("enter")
+  .from("[data-heading]", { yPercent: 110, duration: 0.8 })
+  .from("[data-lead]", { autoAlpha: 0, y: 18, duration: 0.6 }, "-=0.5")
+  .addLabel("emphasis")
+  .add(mark())                       // a beat of its own, built elsewhere
+  .addLabel("rest");
+```
+
+Two rules follow from it:
+
+- **A beat that is more than one tween is a function returning its own
+  timeline**, added with `.add()`. The scene then reads as its beats, and the
+  beat can be retimed, reordered or dropped without touching the rest.
+- **An ambient loop is handed off after the scene, never added inside it.** An
+  infinite child makes the parent infinite, so the scene's own `onComplete`
+  never runs and anything waiting on it waits forever — the audit reports that
+  as `never-completes`. Start the loop from a `.call()` at the end, or from the
+  scene's `onComplete`.
+
+The numbered beats in an answer's Motion strategy and the labels in its code are
+the same list. If they have drifted apart, the code is not what was designed.
+
 ## Position
 
 The third argument places a child on the timeline. This is the whole API.

package/skill/scripts/lib/rules.mjs

@@ -53,6 +53,16 @@ const HINT = {
     "Inside a context these register themselves and are reverted with it. Out here nothing is watching: move it into the useGSAP body, or keep the instance and revert/kill it from the cleanup.",
   unrevertedContext:
     "Keep it under a name and revert it when the component goes: `onUnmounted` in Vue, the function returned from `onMount` or `$effect` in Svelte, the `useEffect` cleanup in React, `astro:before-swap` in Astro. Everything created inside the context goes with it.",
+  tweenPerFrame:
+    "A tween per frame allocates an object per frame, and each one fights the last. Create a `gsap.quickTo()` or `quickSetter()` once outside the callback and call it inside — or, for scroll, scrub a timeline instead of writing values by hand.",
+  paintProperty:
+    "Filters and shadows repaint the layer every frame, and the cost grows with the painted area. Animate `opacity` on a pre-blurred or pre-shadowed copy, or move a transform instead, and measure before defending anything else.",
+  unownedLoop:
+    "An infinite repeat keeps the ticker busy while it is off screen. Pause it from an IntersectionObserver, or let a ScrollTrigger's `onToggle` own it, so it costs nothing when nobody can see it.",
+  ungatedHover:
+    "A tap fires `mouseenter` on a touch device and nothing fires the leave, so the effect sticks. Gate it with `gsap.matchMedia()` on `(hover: hover)`, and decide what a coarse pointer gets instead.",
+  delayChain:
+    "Delays are a choreography nobody can change: moving one beat means re-adding every number after it. Build a timeline and position each beat with a label or a relative offset — `\"<\"`, `\"-=0.2\"`.",
   danglingListener:
     "A listener that survives unmount keeps the component's closure — and its DOM nodes — alive. Name the handler and remove it in the cleanup, or pass `{ signal }` from an AbortController and abort it there.",
   tweenPerEvent:
@@ -87,6 +97,10 @@ const HINT = {
 /** Messages that do not vary with what was found. */
 const MESSAGE = {
   easedLoop: "An infinite repeat with an ease other than `none`.",
+  tweenPerFrame: "A tween is created here on every frame.",
+  unownedLoop: "An infinite repeat that nothing pauses.",
+  ungatedHover: "A hover animation with no `(hover: hover)` gate.",
+  delayChain: "Three or more tweens in this scope are sequenced by `delay`.",
   easedScrub: "Easing inside a scrubbed ScrollTrigger timeline.",
   neverCompletesChild:
     "An endlessly repeating child in a timeline with an `onComplete`, which therefore never fires.",
@@ -414,6 +428,13 @@ function notPerEvent(ast, handler, node) {
 }
 
 /** Listener targets that outlive every component: the window, the document and its root elements. */
+/**
+ * Events that fire once and are never removed by anyone: the document's own
+ * start-up. The corpus reported two `DOMContentLoaded` handlers in an Astro
+ * page as leaks, which is not what a leak is.
+ */
+const ONE_SHOT_EVENTS = new Set(["DOMContentLoaded", "load", "pageshow"]);
+
 const GLOBAL_TARGETS = new Set([
   "window",
   "document",
@@ -547,6 +568,119 @@ function mountHook(ast, node) {
   return null;
 }
 
+/**
+ * Properties whose animation repaints the element rather than moving a layer
+ * the compositor already has.
+ *
+ * `clipPath` is deliberately absent. An inset or circle reveal is the technique
+ * this skill recommends for image reveals, it is cheap on a simple shape, and a
+ * rule that fires on its own guidance is noise.
+ */
+const PAINT_PROPERTIES = new Set([
+  "filter",
+  "webkitFilter",
+  "backdropFilter",
+  "boxShadow",
+]);
+
+const HOVER_EVENTS = new Set([
+  "pointerenter",
+  "pointerover",
+  "mouseenter",
+  "mouseover",
+]);
+
+/**
+ * Every function that runs once per frame: the ticker, R3F's `useFrame`, an
+ * `onUpdate`/`onMove`/`onChange` callback, and a function that schedules
+ * itself with `requestAnimationFrame`.
+ */
+function perFrameScopes(ast) {
+  const scopes = [];
+  const add = (node) => {
+    const fn = node && unwrap(node);
+    if (isFunction(fn)) scopes.push(fn);
+  };
+
+  for (const call of findAll(ast, (node) => {
+    const name = calleeName(node);
+    return name === "gsap.ticker.add" || name === "useFrame";
+  })) {
+    add(call.arguments[0]);
+  }
+
+  /**
+   * `onUpdate`, `onMove` and `onChange` are per-frame in a tween, a
+   * ScrollTrigger, an Observer or a Draggable — and nowhere else. Every control
+   * and form library in the world has an `onChange`, and the corpus duly
+   * reported a Three.js `traverse` inside one of them as a per-frame tween.
+   */
+  const PER_FRAME_KEYS = new Set(["onUpdate", "onMove", "onChange"]);
+  const GSAP_CONFIG = /^(?:gsap\.|ScrollTrigger\.|Observer\.|Draggable\.|ScrollSmoother\.|Flip\.)/;
+
+  for (const property of findAll(
+    ast,
+    (node) => node.type === "Property" && PER_FRAME_KEYS.has(keyName(node)),
+  )) {
+    const owner = ancestorsOf(ast, property).find(
+      (node) => node.type === "CallExpression",
+    );
+    if (!owner) continue;
+    const name = calleeName(owner);
+    if (tweenMethod(owner) === null && !(name && GSAP_CONFIG.test(name))) continue;
+    add(property.value);
+  }
+
+  for (const call of findAll(
+    ast,
+    (node) => calleeName(node) === "requestAnimationFrame",
+  )) {
+    const fn = resolveFunction(ast, call.arguments[0]);
+    if (isFunction(fn) && contains(fn, call)) scopes.push(fn);
+  }
+
+  return scopes;
+}
+
+/** The handlers a hover starts: a listener's callback, or a JSX `on*` prop. */
+function hoverHandlers(ast) {
+  const handlers = [];
+
+  for (const call of findAll(
+    ast,
+    (node) => listenerMethod(node) === "addEventListener",
+  )) {
+    const event = staticString(call.arguments[0]);
+    if (event === null || !HOVER_EVENTS.has(event)) continue;
+    const fn = resolveFunction(ast, call.arguments[1]);
+    if (isFunction(fn)) handlers.push(fn);
+  }
+
+  for (const attribute of findAll(
+    ast,
+    (node) => node.type === "JSXAttribute" && node.name.type === "JSXIdentifier",
+  )) {
+    if (!/^on(?:Mouse|Pointer)(?:Enter|Over)$/.test(attribute.name.name)) continue;
+    if (attribute.value?.type !== "JSXExpressionContainer") continue;
+    const fn = resolveFunction(ast, attribute.value.expression);
+    if (isFunction(fn)) handlers.push(fn);
+  }
+
+  return handlers;
+}
+
+/** Whether anything in the file pauses, kills or reverts what is kept as `name`. */
+function stopped(ast, name) {
+  if (!name) return false;
+  return (
+    findAll(ast, (node) => {
+      const method = methodName(node);
+      if (method !== "pause" && !TEARDOWN.has(method)) return false;
+      return dottedName(unwrap(node.callee).object) === name;
+    }).length > 0
+  );
+}
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -687,6 +821,7 @@ export const RULES = [
           const event = staticString(call.arguments[0]);
           const handler = unwrap(call.arguments[1]);
           if (event === null || !/^[\w:-]+$/.test(event) || !handler) return [];
+          if (ONE_SHOT_EVENTS.has(event)) return [];
           const options = unwrap(call.arguments[2]);
           const once = unwrap(propertyOf(options, "once")?.value);
           const callee = unwrap(call.callee);
@@ -1184,6 +1319,177 @@ export const RULES = [
       return findings;
     },
   },
+  {
+    id: "tween-per-frame",
+    level: "warn",
+    description:
+      "A tween created every frame — in `onUpdate`, the ticker, an Observer callback, `useFrame` or a `requestAnimationFrame` loop",
+    /**
+     * `gsap.set` is left out: writing a value straight to an element is what a
+     * per-frame callback is for, and `quickSetter` is the faster shape of the
+     * same thing rather than a different one. What this catches is a tween —
+     * an object with its own duration and ease — being built sixty times a
+     * second, each one overwriting the last before it can finish.
+     */
+    test(file) {
+      const scopes = perFrameScopes(file.ast);
+      if (scopes.length === 0) return [];
+
+      const tweens = findAll(file.ast, (node) => {
+        const method = tweenMethod(node);
+        return method !== null && method !== "set";
+      });
+
+      const reported = new Set();
+      const findings = [];
+      for (const scope of scopes) {
+        for (const tween of tweens) {
+          if (!contains(scope, tween) || reported.has(tween.start)) continue;
+          reported.add(tween.start);
+          findings.push({
+            index: tween.start,
+            message: MESSAGE.tweenPerFrame,
+            hint: HINT.tweenPerFrame,
+          });
+        }
+      }
+      return findings;
+    },
+  },
+  {
+    id: "paint-property",
+    level: "warn",
+    description:
+      "Animating `filter`, `backdropFilter` or `boxShadow`, which repaints the element every frame",
+    /** Read exactly as layout-property reads its own keys, and `set` is skipped too. */
+    test(file) {
+      const animates = (node) => {
+        const method = tweenMethod(node);
+        return method !== null && method !== "set";
+      };
+
+      return findAll(file.ast, animates).flatMap((call) => {
+        const seen = new Set();
+        return varsObjects(call, tweenMethod(call))
+          .flatMap((vars) => vars.properties)
+          .filter((property) => {
+            const key = keyName(property);
+            if (!PAINT_PROPERTIES.has(key) || seen.has(key)) return false;
+            seen.add(key);
+            return true;
+          })
+          .map((property) => ({
+            index: property.start,
+            message: `Animating \`${keyName(property)}\` repaints on every frame.`,
+            hint: HINT.paintProperty,
+          }));
+      });
+    },
+  },
+  {
+    id: "unowned-loop",
+    level: "info",
+    description:
+      "An infinite repeat that nothing pauses, which keeps the ticker busy off screen",
+    /**
+     * Info, because "nothing pauses it" is read from one file and a loop can be
+     * owned from elsewhere. A loop is taken as owned when its name is paused,
+     * killed or reverted anywhere here, when the file builds an
+     * IntersectionObserver, when the tween carries a `scrollTrigger` that
+     * toggles it, or when a context holds it — unmount reverts that one.
+     *
+     * The last of those came from a real site's loader, where three loops sit
+     * in a `useGSAP` body inside `matchMedia`. Reporting them would have meant
+     * "nothing stops this" about an animation the component's own unmount stops.
+     * What is left — a loop running while it is off screen but still mounted —
+     * is a measurement, and 3.4's `inspect` is where that belongs.
+     */
+    test(file) {
+      const observed = findAll(
+        file.ast,
+        (node) =>
+          node.type === "NewExpression" &&
+          dottedName(node.callee) === "IntersectionObserver",
+      ).length > 0;
+      if (observed) return [];
+
+      const inside = gsapContexts(file.ast);
+
+      return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap((call) => {
+        if (inside(call)) return [];
+        const vars = ownVars(call, tweenMethod(call));
+        if (!vars) return [];
+        const repeat = propertyOf(vars, "repeat");
+        if (!repeat || numberValue(repeat.value) !== -1) return [];
+        if (propertyOf(vars, "scrollTrigger")) return [];
+        if (stopped(file.ast, keptUnder(file.ast, call)?.name)) return [];
+        return [
+          {
+            index: repeat.start,
+            message: MESSAGE.unownedLoop,
+            hint: HINT.unownedLoop,
+          },
+        ];
+      });
+    },
+  },
+  {
+    id: "ungated-hover",
+    level: "warn",
+    description:
+      "A hover animation with no `(hover: hover)` gate, which a tap starts and nothing ends",
+    /**
+     * The gate is looked for as text, anywhere in the file: a `matchMedia`
+     * condition, a CSS string, a constant. One finding per handler, on its first
+     * tween, because the handler is what needs the gate.
+     */
+    test(file) {
+      if (/\(\s*(?:any-)?hover\s*:\s*hover\s*\)/.test(file.code)) return [];
+
+      return hoverHandlers(file.ast).flatMap((handler) => {
+        const [tween] = findAll(file.ast, (node) => tweenMethod(node) !== null).filter(
+          (node) => contains(handler, node),
+        );
+        if (!tween) return [];
+        return [
+          { index: tween.start, message: MESSAGE.ungatedHover, hint: HINT.ungatedHover },
+        ];
+      });
+    },
+  },
+  {
+    id: "delay-chain",
+    level: "warn",
+    description:
+      "Three or more tweens in one scope sequenced by `delay`, which is a timeline nobody can retime",
+    /**
+     * Three is the threshold because two tweens with delays are a pair, and a
+     * pair is still readable. Counted per scope — the function they share — so
+     * three components each with one delayed tween are not a chain. A tween on a
+     * timeline is not counted: a timeline already has positions.
+     */
+    test(file) {
+      const scopes = new Map();
+
+      for (const call of findAll(file.ast, (node) => tweenMethod(node) !== null)) {
+        if (chainStart(call) !== call) continue;
+        const vars = ownVars(call, tweenMethod(call));
+        const delay = vars && propertyOf(vars, "delay");
+        if (!delay || !(numberValue(delay.value) > 0)) continue;
+        const scope = scopeOf(file.ast, call) ?? file.ast;
+        if (!scopes.has(scope)) scopes.set(scope, []);
+        scopes.get(scope).push(call);
+      }
+
+      return [...scopes.values()]
+        .filter((calls) => calls.length >= 3)
+        .map((calls) => ({
+          index: calls[0].start,
+          message: MESSAGE.delayChain,
+          hint: HINT.delayChain,
+        }));
+    },
+  },
   {
     id: "missing-reduced-motion",
     level: "warn",
@@ -1191,23 +1497,28 @@ export const RULES = [
       "An animating file with no `prefers-reduced-motion` branch",
     /**
      * A branch is the query written in code — a string, a template or JSX
-     * text. A comment that mentions it is not a branch. A file that only sets
-     * values is not animating anything.
+     * text. A comment that mentions it is not a branch.
+     *
+     * Only a file that builds an animation of its own is reported, and the
+     * finding lands on the first one. Three things are not that:
+     * `registerPlugin` and `killTweensOf`, which animate nothing; `set`, which
+     * has no duration; and a method called on a timeline the file was handed,
+     * because a helper that adds beats to its caller's timeline does not own
+     * the reduced-motion decision — the caller does.
      */
     test(file) {
       if (!file.usesGsap) return [];
       if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
         return [];
       }
-      if (!findAll(file.ast, (node) => isGsapCall(node)).length) return [];
 
-      const first = findAll(
-        file.ast,
-        (node) =>
-          node.type === "MemberExpression" &&
-          unwrap(node.object)?.type === "Identifier" &&
-          unwrap(node.object).name === "gsap",
-      ).sort((a, b) => a.start - b.start)[0];
+      const [first] = findAll(file.ast, (node) => {
+        const method = tweenMethod(node);
+        if (method === null || method === "set") return false;
+        /** Built here, rather than added to something passed in. */
+        return calleeName(node)?.startsWith("gsap.") === true;
+      }).sort((a, b) => a.start - b.start);
+      if (!first) return [];
 
       return [
         {