@mehshekari/gsap-motion 3.2.0 → 3.4.0

package/README.md

@@ -20,6 +20,8 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `remove` | Uninstalls it. Takes the same `--global` and `--dir`. It only ever removes a directory that holds this skill. |
 | `audit [path...]` | Scans for leaks, per-frame cost, eased loops, shared plugin ids, unregistered plugins and shipped dev tooling. Default path `src`. `--quiet` for errors only, `--json` for scripts. |
 | `audit-svg <file...>` | Reports what DrawSVG can draw, what MorphSVG can morph, and what will fail silently. `--morph a.svg b.svg` compares a pair; `--hues` also reports hard-coded hues. |
+| `inspect <url>` | Watches a page animate over the DevTools Protocol and reports what it saw: a filmstrip, the timeline GSAP is running, and the layouts, style recalculations and frames the browser did. `--scroll`, `--hover` and `--click` reach the state first; `--reduced`, `--dark`, `--mobile` and `--cpu` change the conditions. Needs a Chrome on the machine; installs nothing. |
+| `explain <file...|url>` | Maps an animation and changes nothing: where it lives, its preference branches, its beats in order with the reasons their comments give, its scroll configuration, and what the audit says. Given a URL it reads the running page instead, where the timeline is the one GSAP actually built. |
 | `doctor` | Checks Node.js, the installed skill's version for this project and your user, your project's `gsap` and `@gsap/react`, and whether an `ANIMATION.md` exists. |
 
 ## In CI
@@ -28,7 +30,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.4.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -7,6 +7,8 @@
  *   npx @mehshekari/gsap-motion remove [--global | --dir <skills-dir>]
  *   npx @mehshekari/gsap-motion audit [path...] [--quiet] [--json]
  *   npx @mehshekari/gsap-motion audit-svg <file.svg...> [--morph] [--hues]
+ *   npx @mehshekari/gsap-motion inspect <url> [--at ...] [--hover ...] [--reduced]
+ *   npx @mehshekari/gsap-motion explain <file...|url>
  *   npx @mehshekari/gsap-motion doctor
  *
  * Installed as a dependency, the same commands run as `gsap-motion <command>`.
@@ -69,6 +71,19 @@ Commands
   audit-svg <file...>   What an SVG can do before you animate it
     --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
+    --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
+    --cpu 4             Throttle the CPU by this factor
+    --out <dir>         Where frames go. Default .gsap-motion/inspect
+    --json              Machine-readable output
+  explain <file...>     Map an animation: scopes, branches, beats, triggers
+                        Give it a URL instead to read the running page
+    --json              Machine-readable output
   doctor                Check Node, the installed skill and your project's GSAP
   --version             Print the version
 
@@ -301,6 +316,12 @@ switch (command) {
   case "audit-svg":
     runScript("audit-svg.mjs", args);
     break;
+  case "inspect":
+    runScript("capture-motion.mjs", args);
+    break;
+  case "explain":
+    runScript("explain-motion.mjs", args);
+    break;
   case "doctor":
     doctor();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.2.0",
+  "version": "3.4.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.4.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,27 +163,31 @@ 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.
+These catch what is **silent**. Run them from the project root; `<skill-dir>`
+is the skill's folder.
 
 ```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,
+# 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
+node <skill-dir>/scripts/audit-gsap.mjs src --json
 
-# What an SVG can actually do, before any animation is written.
+# What an SVG can do, before any animation is written.
 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>   # also flag hue literals
+node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>
+
+# Watch a page animate: frames, timeline, browser work.
+# Needs a Chrome; observations, not verdicts.
+node <skill-dir>/scripts/capture-motion.mjs <url> --at 0,300,900
 ```
 
-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 animation — as a plugin,
+a hook already runs it on every edit. 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 it once its 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,112 @@
+# 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.
+
+When what the code says and what the page does disagree, `explain-motion.mjs`
+reads both: the file's map, or — given a URL — the timeline GSAP actually built.
+
+## 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.
+
+## Watch it, when you can
+
+A checker reads code. It cannot see a seam, a slideshow, or a hero that starts
+so late the visitor has already scrolled past it. When a browser is on the
+machine, run the page:
+
+```bash
+node <skill-dir>/scripts/capture-motion.mjs http://localhost:3000 --at 0,300,900
+```
+
+It reports a filmstrip, the timeline GSAP is actually running — which is not
+always the one in the source — and the layouts, style recalculations and frames
+the browser did. All observations; the judgement is yours.
+
+Reach the state first, and change the conditions that usually break things:
+
+- `--scroll <px|selector>`, `--hover <selector>`, `--click <selector>` run in
+  the order written, before the first capture. A hover effect or a mid-page
+  ScrollTrigger is invisible without them.
+- `--reduced`, `--dark`, `--mobile`, `--cpu 4`. `--mobile` makes input touch,
+  so it cannot be combined with `--hover`: a coarse pointer has no hover, which
+  is the thing worth knowing.
+
+**Without a browser, report the stage as not run.** Not "fine".
+
+## 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.
@@ -82,6 +99,18 @@ the mechanical failures before you spend attention on them:
 node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
 ```
 
+**Read the map before reading the code.** `explain-motion.mjs` prints what a
+file animates — scopes, preference branches, beats in order with the reasons
+their comments give, and the scroll configuration — and cites the audit rather
+than judging. Given a URL it reads the running page instead, which is the only
+way to see the timeline GSAP actually built, after every branch and early
+return:
+
+```bash
+node <skill-dir>/scripts/explain-motion.mjs src/hooks/useHero.ts
+node <skill-dir>/scripts/explain-motion.mjs http://localhost:3000
+```
+
 **When an animation is not visible, ask whether it was ever built.** Before
 touching timings or transforms, check that the code which creates it actually
 runs. Animation is routinely built behind a condition — an image decode race, a

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.