@mehshekari/gsap-motion 4.3.0 → 4.5.0

package/README.md

@@ -32,7 +32,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@4.3.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.5.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -74,15 +74,21 @@ Commands
     --morph <a> <b>     Compare a morph pair
     --hues              Also report hard-coded hues
   inspect <url>         Watch a page animate and report what it did
-    --at 0,300,900      When to capture, in ms after the page settles
+    --at 0,300,900      When to capture, in ms after --wait
+    --wait 400          A fixed wait after navigation; it does not detect a loader
     --scroll <px|sel>   Scroll before capturing
     --hover <selector>  Move the pointer onto an element
     --click <selector>  Click an element
     --reduced --dark    Emulate a preference
     --mobile            390x844 with touch input
+    --viewport 1440x900 The window's size; every report prints the one used
     --cpu 4             Throttle the CPU by this factor
+    --headed            A visible Chrome on the GPU, for WebGL pages
+    --seek <name>       Call window.<name>(t) before each capture; --at is
+                        then seconds of the timeline
     --out <dir>         Where frames go. Default .gsap-motion/inspect
     --json              Machine-readable output
+    --probe timeline    Print the timeline reader for a browser you drive
   explain <file...>     Map an animation: scopes, branches, beats, triggers
                         Give it a URL instead to read the running page
     --json              Machine-readable output
@@ -92,9 +98,13 @@ Commands
     --scroll <px|sel>   Scroll, then watch again
     --reduced --dark    Emulate a preference
     --mobile            390x844 with touch input
+    --viewport 1440x900 The window's size; every report prints the one used
     --cpu 4             Throttle the CPU by this factor
+    --headed            A visible Chrome on the GPU, for WebGL pages
     --out <dir>         Save a frame alongside the measurements
     --json              Machine-readable output
+    --probe install|read  Print the recorder, or its findings, for a browser
+                        you drive — such as a DevTools MCP server
   patterns check [file] Check the Patterns section of your ANIMATION.md:
                         the fields each status needs, the uses behind
                         validated, the reviewer behind canonical
@@ -290,7 +300,15 @@ function doctor(args = []) {
       if (provider) report("info", `No separate copy for ${scope}`);
       else report("info", `Not installed for ${scope}`, `${command} installs it at ${location}`);
     } else if (installed.version === bundled.version) {
-      report("ok", `Installed for ${scope}: ${installed.version}`);
+      if (provider) {
+        report(
+          "warn",
+          `Installed for ${scope}: ${installed.version}`,
+          `The ${provider} plugin provides it too, so the skill is listed twice. Remove ${location}.`,
+        );
+      } else {
+        report("ok", `Installed for ${scope}: ${installed.version}`);
+      }
     } else {
       report(
         "warn",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "4.3.0",
+  "version": "4.5.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 22+ and nothing else.
 metadata:
-  version: "4.3.0"
+  version: "4.5.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -75,8 +75,8 @@ Core principles:
 - **A command, explicit or implied:** load its reference and follow it.
 - **A description** ("make this feel like Apple", "the hero is boring"): that is
   `create`. 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.
+- **Two commands fit:** use both, and say so in a line. A scroll-driven text
+  reveal is `scroll` and `text` together.
 - **`design` stops at the plan.** `build` implements one that was approved, and
   needs it in hand. `evolve` improves what is there and never adds motion.
 
@@ -109,7 +109,8 @@ intent → precedent → targets → trigger → motion language → technique
 
 ## Output format
 
-For anything beyond a one-line tweak, answer in this shape, each part short:
+Beyond a one-line tweak, use this shape, each part short, unless the user or
+project asks for another:
 
 - **Analysis** — what moves, why, on what trigger, and the intent you read it
   as, with the values that follow.
@@ -160,8 +161,7 @@ These catch what is **silent**. Run them from the project root; `<skill-dir>`
 is the skill's folder.
 
 ```bash
-# Leaks, per-event and per-frame tweens, layout and paint properties, loops,
-# plugin ids, unregistered plugins, dev tooling. Exit 1 on an error.
+# Silent failures: leaks, per-frame cost, plugins, dev tooling. Exit 1 on 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
@@ -171,8 +171,8 @@ node <skill-dir>/scripts/audit-svg.mjs <file.svg>
 node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
 node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>
 
-# Both need a Chrome. Watch a page animate; then measure what it did:
-# first motion, screen share, seams, motion over text.
+# Both open a Chrome (refine.md: --probe, for yours). Watch a page animate,
+# then measure: first motion, screen share, seams, motion over text.
 node <skill-dir>/scripts/capture-motion.mjs <url> --at 0,300,900
 node <skill-dir>/scripts/review-motion.mjs <url> --scroll 2000
 ```

package/skill/adapter/next.md

@@ -27,8 +27,7 @@ must survive one belongs in the layout.
 
 ## Scope
 
-As in react.md, and `useId` matters more here: the markup is rendered on the
-server and again on the client, and a counter would disagree between them.
+As in react.md.
 
 ## Server rendering and hydration
 

package/skill/adapter/r3f.md

@@ -112,12 +112,15 @@ was created inside the body.
 | The tween starts before the object exists | no early return on a null ref |
 | Memory grows across route changes | objects created outside JSX, never disposed |
 | Scroll-driven camera drifts out of sync | a scrub with an ease on a child, instead of `ease: "none"` |
+| One long frame the first time a section scrolls in | shaders compiled on first draw — see [performance.md](../reference/performance.md#webgl-the-first-frame-of-each-material) |
+| Scene stays black | WebGL context lost — see [performance.md](../reference/performance.md#webgl-losing-the-context-and-reading-it-back) |
 
 ## What the audit covers
 
 The React rules from react.md, since these are `.tsx` files. From 3.2,
 `useFrame` counts as a per-frame scope, so React state set inside it is reported
-as `state-per-event`.
+as `state-per-event`, and a Three vector or colour built in it as
+`allocation-per-frame`.
 
 Disposal, GPU cost and the render loop are not checkable — read for them, and
 measure with [performance.md](../reference/performance.md).

package/skill/adapter/react.md

@@ -34,13 +34,18 @@ body re-runs on change) and `revertOnUpdate` (the previous run reverts first).
 
 A tween created *outside* the body — in a handler, a promise, a callback — is
 never reverted. Wrap that function in `contextSafe`, from the same hook, and the
-context owns it again. Only wrap functions that *create* animations: playing an
-existing timeline creates nothing. Inside `mm.add`, use its own: the callback's
+context owns it — with every tween it makes, killed ones too, until it reverts.
+A frequent handler replays a timeline built in the body, or calls a `quickTo`. Inside `mm.add`, use its own: the callback's
 second argument, `(context, contextSafe) =>`. `contextSafe` runs during render, so reading a
 ref inside the callback trips React's "cannot access refs during render" rule —
 build the timeline in the body, keep it on a ref, and expose a `useCallback`
 that plays it.
 
+**Without `@gsap/react`, write it by hand:** a `gsap.context(fn, root)` or
+`gsap.matchMedia()` created in `useLayoutEffect`, its `revert` returned as the
+cleanup. The audit reads that as it reads `useGSAP`. `ctx.add(null, fn)` is
+`contextSafe`; `ctx.add(fn)` runs `fn` at once (verified against gsap 3.15).
+
 ## Where it is torn down
 
 `useGSAP` reverts its context on unmount. Tweens, timelines, `ScrollTrigger`,
@@ -98,8 +103,7 @@ onMouseMove = (e) => moveX(e.clientX);
 ```
 
 State is for *what exists* — is the modal open, which tab is active. GSAP owns
-*how it moves*. Crossing that line is the most common performance bug in
-animated React.
+*how it moves*.
 
 ## Page and route changes
 
@@ -118,7 +122,6 @@ App Router. After a navigation, `ScrollTrigger.refresh()` once it settles.
 | Two components animate each other | missing `scope`, or a shared hardcoded id |
 | Hydration mismatch | storage or a media query read during render |
 | Janky pointer effect | React state in the handler |
-| Hover sticks halfway | no `overwrite: "auto"` on the retriggered tween |
 
 ## What the audit covers
 

package/skill/adapter/three.md

@@ -115,6 +115,8 @@ is a live GPU context for a page that is gone.
 | Memory grows on every visit | geometries, materials or textures never disposed |
 | The camera snaps back every frame | `lookAt` overwriting a tweened rotation |
 | The page is slow on phones before anything moves | Three in the initial bundle instead of imported dynamically |
+| One long frame the first time a section scrolls in | shaders compiled on first draw — see [performance.md](../reference/performance.md#webgl-the-first-frame-of-each-material) |
+| Scene stays black | WebGL context lost — see [performance.md](../reference/performance.md#webgl-losing-the-context-and-reading-it-back) |
 
 ## Cost and accessibility
 

package/skill/example/magnetic-button.md

@@ -1,101 +1,101 @@
-# Example: magnetic CTA
-
-A worked interaction, end to end, showing the shape of the answer this skill
-should produce.
-
-## Analysis
-
-- **Animating** — a primary CTA and its label.
-- **Why** — the button should feel like it wants to be pressed. The response
-  begins before the cursor arrives, which reads as intent rather than as a
-  hover state.
-- **Style** — premium and restrained. Small travel, long ease, no overshoot.
-- **Trigger** — pointer movement inside a padded zone; leave returns it.
-- **Techniques** — `gsap.quickTo` for the tracking, a paused timeline for the
-  hover state. No plugins. MotionPath and Draggable would both be wrong here.
-
-## Motion strategy
-
-1. The pointer enters the zone — a 32px halo around the button.
-2. The button eases toward the cursor at 32% of the offset.
-3. The label travels half again as far, so the face has depth.
-4. Simultaneously the button scales to 1.04 and its shadow deepens.
-5. On leave, everything eases back to rest over 0.6s.
-
-The return is the part that makes it feel physical, and the part most
-implementations get wrong by snapping.
-
-## Architecture
-
-- `quickTo` functions created once, in the `useGSAP` body — not a tween per
-  pointer event. This is the whole performance story.
-- A paused hover timeline, played and reversed, so the return matches the
-  arrival without a second definition.
-- `gsap.matchMedia` gating on `(hover: hover) and (pointer: fine)` **and**
-  `prefers-reduced-motion: no-preference`. Both gates are load-bearing.
-- Listeners removed in the `matchMedia` callback's own cleanup. `mm` itself
-  needs no revert: it registers with the active GSAP context and goes with it.
-
-## Implementation
-
-The hook is in [preset/magnetic.md](../preset/magnetic.md) — copy it rather than
-duplicating it here.
-
-```tsx
-"use client";
-
-import { useMagnetic } from "./useMagnetic";
-
-export function MagneticCta({
-  label,
-  onPress,
-}: Readonly<{ label: string; onPress: () => void }>) {
-  const { zoneRef, targetRef, labelRef } = useMagnetic();
-
-  return (
-    // The zone's padding is the field radius — the pull starts here, not at
-    // the button's edge. That is what turns a hover state into a field.
-    <div ref={zoneRef} className="inline-flex p-8">
-      <button
-        ref={targetRef as React.RefObject<HTMLButtonElement>}
-        type="button"
-        onClick={onPress}
-        // The focus ring carries the whole affordance for a keyboard, which
-        // never sees the pull at all.
-        className="rounded-full bg-neutral-900 px-7 py-3 text-sm font-medium text-white shadow-lg focus-visible:ring-2"
-      >
-        <span ref={labelRef} className="inline-block">
-          {label}
-        </span>
-      </button>
-    </div>
-  );
-}
-```
-
-## Usage
-
-```tsx
-<MagneticCta label={t("cta.contact")} onPress={open} />
-```
-
-The label is a message key resolved by the caller.
-
-## Notes
-
-- **Responsive** — the effect does not exist on touch. The button is an
-  ordinary button there, which is correct; nothing is lost.
-- **Performance** — two `quickTo` functions, no allocation per event, only
-  transforms. The rect is measured per move because scroll shifts it; if that
-  shows in a profile, cache on enter and invalidate on scroll.
-- **Reduced motion** — no pull, no scale. The hover and focus states remain as
-  instant colour and shadow changes, so the affordance survives.
-- **Accessibility** — focus state equals hover state. The transform is small
-  enough that the focus ring stays under the element.
-- **Dependencies** — none beyond `gsap` and `@gsap/react`.
-
-## Related
-
-[preset/magnetic.md](../preset/magnetic.md) ·
-[reference/interaction.md](../reference/interaction.md) ·
-[reference/performance.md](../reference/performance.md)
+# Example: magnetic CTA
+
+A worked interaction, end to end, showing the shape of the answer this skill
+should produce.
+
+## Analysis
+
+- **Animating** — a primary CTA and its label.
+- **Why** — the button should feel like it wants to be pressed. The response
+  begins before the cursor arrives, which reads as intent rather than as a
+  hover state.
+- **Style** — premium and restrained. Small travel, long ease, no overshoot.
+- **Trigger** — pointer movement inside a padded zone; leave returns it.
+- **Techniques** — `gsap.quickTo` for the tracking, a paused timeline for the
+  hover state. No plugins. MotionPath and Draggable would both be wrong here.
+
+## Motion strategy
+
+1. The pointer enters the zone — a 32px halo around the button.
+2. The button eases toward the cursor at 32% of the offset.
+3. The label travels half again as far, so the face has depth.
+4. Simultaneously the button scales to 1.04 and its shadow deepens.
+5. On leave, everything eases back to rest over 0.6s.
+
+The return is the part that makes it feel physical, and the part most
+implementations get wrong by snapping.
+
+## Architecture
+
+- `quickTo` functions created once, in the `useGSAP` body — not a tween per
+  pointer event. This is the whole performance story.
+- A paused hover timeline, played and reversed, so the return matches the
+  arrival without a second definition.
+- `gsap.matchMedia` gating on `(hover: hover) and (pointer: fine)` **and**
+  `prefers-reduced-motion: no-preference`. Both gates are load-bearing.
+- Listeners removed in the `matchMedia` callback's own cleanup. `mm` itself
+  needs no revert: it registers with the active GSAP context and goes with it.
+
+## Implementation
+
+The hook is in [preset/magnetic.md](../preset/magnetic.md) — copy it rather than
+duplicating it here.
+
+```tsx
+"use client";
+
+import { useMagnetic } from "./useMagnetic";
+
+export function MagneticCta({
+  label,
+  onPress,
+}: Readonly<{ label: string; onPress: () => void }>) {
+  const { zoneRef, targetRef, labelRef } = useMagnetic();
+
+  return (
+    // The zone's padding is the field radius — the pull starts here, not at
+    // the button's edge. That is what turns a hover state into a field.
+    <div ref={zoneRef} className="inline-flex p-8">
+      <button
+        ref={targetRef as React.RefObject<HTMLButtonElement>}
+        type="button"
+        onClick={onPress}
+        // The focus ring carries the whole affordance for a keyboard, which
+        // never sees the pull at all.
+        className="rounded-full bg-neutral-900 px-7 py-3 text-sm font-medium text-white shadow-lg focus-visible:ring-2"
+      >
+        <span ref={labelRef} className="inline-block">
+          {label}
+        </span>
+      </button>
+    </div>
+  );
+}
+```
+
+## Usage
+
+```tsx
+<MagneticCta label={t("cta.contact")} onPress={open} />
+```
+
+The label is a message key resolved by the caller.
+
+## Notes
+
+- **Responsive** — the effect does not exist on touch. The button is an
+  ordinary button there, which is correct; nothing is lost.
+- **Performance** — two `quickTo` functions, no allocation per event, only
+  transforms. The rect is measured per move because scroll shifts it; if that
+  shows in a profile, cache on enter and invalidate on scroll.
+- **Reduced motion** — no pull, no scale. The hover and focus states remain as
+  instant colour and shadow changes, so the affordance survives.
+- **Accessibility** — focus state equals hover state. The transform is small
+  enough that the focus ring stays under the element.
+- **Dependencies** — none beyond `gsap` and `@gsap/react`.
+
+## Related
+
+[preset/magnetic.md](../preset/magnetic.md) ·
+[reference/interaction.md](../reference/interaction.md) ·
+[reference/performance.md](../reference/performance.md)