@mehshekari/gsap-motion 3.1.1 → 3.2.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.1.1 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.2.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -257,6 +257,23 @@ function doctor() {
     );
   }
 
+  /**
+   * Which adapters the skill loads here, read the way SKILL.md's setup step 3
+   * describes. Deterministic, so the stack is looked up rather than guessed.
+   */
+  const picked = new Set();
+  if (deps.next) picked.add("react").add("next");
+  if (deps["@react-three/fiber"]) picked.add("react").add("r3f");
+  else if (deps.three) picked.add("three");
+  if (deps.react) picked.add("react");
+  if (deps.vue || deps.nuxt) picked.add("vue");
+  if (deps.svelte || deps["@sveltejs/kit"]) picked.add("svelte");
+  if (deps.astro) picked.add("astro");
+  if (picked.size === 0) picked.add("vanilla");
+
+  const ORDER = ["react", "next", "r3f", "three", "vue", "svelte", "astro", "vanilla"];
+  report("ok", `Adapters: ${ORDER.filter((name) => picked.has(name)).join(", ")}`);
+
   const rules = existsSync(join(process.cwd(), "ANIMATION.md"));
   report(
     rules ? "ok" : "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.1.1",
+  "version": "3.2.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.1.1"
+  version: "3.2.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -47,9 +47,13 @@ Core principles:
    - **One element, one tween or interaction** — a hover, a fade, a retime:
      [motion-design.md](reference/motion-design.md) and the command's own
      reference. Nothing else.
-   - **A component or section:** also
-     [react-nextjs.md](reference/react-nextjs.md) if `package.json` has
-     `react`, or [frameworks.md](reference/frameworks.md) if it does not.
+   - **A component or section:** also this project's adapter, from
+     `package.json`: `next` → [react](adapter/react.md) +
+     [next](adapter/next.md); `@react-three/fiber` → react +
+     [r3f](adapter/r3f.md); `three` → [three](adapter/three.md); `nuxt` →
+     [vue](adapter/vue.md); `svelte` → [svelte](adapter/svelte.md); `astro` →
+     [astro](adapter/astro.md) plus any island's own; nothing detected →
+     [vanilla](adapter/vanilla.md).
    - **A sequence, scroll scene, intro, transition or audit:** also
      [core-gsap.md](reference/core-gsap.md), and what
      [routing.md](reference/routing.md) adds for that request.
@@ -68,7 +72,7 @@ Core principles:
 | `transition [target]` | Build | Page, route, modal and layout transitions | [reference/flip.md](reference/flip.md) |
 | `loader` | Build | Loading and progress animation | [preset/loader.md](preset/loader.md) |
 | `intro` | Build | Site or section entry sequence | [preset/cinematic.md](preset/cinematic.md) |
-| `three [target]` | Build | GSAP orchestrating Three.js / R3F | [reference/three-r3f.md](reference/three-r3f.md) |
+| `three [target]` | Build | GSAP orchestrating Three.js / R3F | [adapter/three.md](adapter/three.md) |
 | `audit [target]` | Evaluate | Check an existing animation: leaks, cost, a11y | [reference/performance.md](reference/performance.md) |
 | `tune [target]` | Refine | Retime, re-ease, fix rhythm — no new motion | [reference/motion-design.md](reference/motion-design.md) |
 | `strip [target]` | Fix | Remove motion that is not earning its place | [reference/motion-design.md](reference/motion-design.md) |
@@ -134,11 +138,11 @@ after that. Never quietly substitute, and never ship both.
   [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md)
 - **Domains** — [scrolltrigger](reference/scrolltrigger.md) ·
   [svg](reference/svg.md) · [text](reference/text.md) ·
-  [interaction](reference/interaction.md) · [flip](reference/flip.md) ·
-  [three-r3f](reference/three-r3f.md)
-- **Constraints** — [react-nextjs](reference/react-nextjs.md) ·
-  [frameworks](reference/frameworks.md) ·
-  [performance](reference/performance.md) ·
+  [interaction](reference/interaction.md) · [flip](reference/flip.md)
+- **Adapters**, one per stack, chosen in setup step 3 — the same questions for
+  each: lifecycle, scope, server rendering, per-frame values, routes, failures,
+  audit.
+- **Constraints** — [performance](reference/performance.md) ·
   [accessibility](reference/accessibility.md) ·
   [project-rules](reference/project-rules.md)
 - **Presets**, starting points to adapt — [reveal](preset/reveal.md) ·

package/skill/adapter/astro.md

@@ -0,0 +1,111 @@
+# Astro
+
+Astro ships no JavaScript unless you ask for it, and its pages can be swapped
+without a reload. Both facts decide where an animation lives.
+
+## Where it is created
+
+In a component's `<script>`, which Astro bundles and defers. With view
+transitions enabled, a page swap does not re-run it, so build on the page-load
+event rather than at the top level:
+
+```astro
+<script>
+  import gsap from "gsap";
+
+  let ctx;
+
+  document.addEventListener("astro:page-load", () => {
+    ctx = gsap.context(() => {
+      gsap.from("[data-item]", { autoAlpha: 0, y: 24, stagger: 0.06 });
+    });
+  });
+
+  document.addEventListener("astro:before-swap", () => ctx?.revert());
+</script>
+```
+
+`astro:page-load` fires on the first load and after every swap, so this one
+shape covers both. Without view transitions the event still fires once, so the
+same code is correct either way.
+
+Inside a React, Vue or Svelte island, use that framework's adapter instead —
+the island owns its own lifecycle.
+
+## Where it is torn down
+
+`astro:before-swap`, with `ctx.revert()`. Skipping it leaves the previous page's
+ScrollTriggers and listeners bound to elements that are about to be replaced,
+and they accumulate for as long as the visit lasts.
+
+Timers, listeners and observers are yours, in the same handler.
+
+## Scope
+
+Astro's `<script>` is page-wide, not component-scoped: a component used twice on
+a page runs its script once, and selector strings match both instances. Either
+animate them as a set — which is usually what you want — or pass the root in
+with a `data-*` attribute and build one context per matching element.
+
+Plugin config is not scoped either, so generate ids per instance rather than
+hardcoding them.
+
+## Server rendering and hydration
+
+Astro components render to HTML on the server and ship no client JavaScript of
+their own, so there is no hydration to mismatch. The script runs only in the
+browser: reading `window` in it is safe, and the markup it animates is already
+painted.
+
+`client:*` directives decide when an island hydrates. An animation inside one
+does not run until it does — `client:visible` on a section that animates on
+entrance is a race worth avoiding; prefer `client:load` there, or keep the
+animation in the page's own script.
+
+## Reaching the element
+
+`data-*` attributes in the markup, queried inside the context. Astro scopes its
+component styles by adding its own attributes to elements, so a class in the
+markup is not always the class in the DOM — a `data-*` attribute you wrote is.
+
+## Every frame
+
+`gsap.quickTo` or `quickSetter`, created once inside the context. There is no
+component state here to get wrong, which removes the most common React mistake
+and leaves the ordinary one: allocating a tween per event.
+
+## Page and route changes
+
+The events are the contract:
+
+- `astro:page-load` — build, on first load and after every swap
+- `astro:before-swap` — revert, before the old page goes
+- `astro:after-swap` — for anything that must run against the new DOM before it
+  paints, such as `ScrollTrigger.refresh()`
+
+View transitions are opt-in: they come from Astro's router component in the
+layout, named `<ClientRouter />` in current versions and `<ViewTransitions />`
+in older ones. Check which one the project imports before telling anyone to add
+it.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Animation runs on the first page only | built at the top of `<script>` instead of on `astro:page-load` |
+| Triggers pile up while browsing | no `astro:before-swap` revert |
+| The script never runs | `is:inline`, which skips bundling, so the bare import fails |
+| Both instances animate as one | a page-wide script with a document-wide selector |
+| An entrance animation starts late | the island hydrates on `client:visible` |
+
+## What the audit covers
+
+From 3.2 the audit reads the `<script>` block of `.astro` files, with offsets
+kept, so reported lines match the file. It checks that a context built on
+`astro:page-load` is reverted on `astro:before-swap`, along with every rule that
+is not React-specific.
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `astro@7`; the swap events are the
+same in Astro 5 and later, though the router component was renamed.

package/skill/adapter/next.md

@@ -0,0 +1,99 @@
+# Next.js
+
+The App Router, with Server Components. Read [react.md](react.md) first: this is
+only what Next adds.
+
+## Where it is created
+
+In a `"use client"` component, in the `useGSAP` body react.md describes. Keep
+that component a **leaf**, so the page above it stays a Server Component.
+
+**Converting a Server Component is part of the cost, and it is priced before the
+design.** *Is GSAP already on this route?* If a sibling section loads `gsap` and
+`ScrollTrigger`, the marginal cost is this component's own JavaScript — a
+kilobyte or two rather than thirty-odd, which usually settles the argument. If
+nothing on the route loads GSAP, this animation buys the whole library for one
+reveal. *Does anything claim otherwise?* A comment saying the section ships no
+client JavaScript stops being true the moment you add the hook; update it in the
+same change.
+
+Say so in the Notes of your answer: "it becomes a client component" is a fact
+the reader needs.
+
+## Where it is torn down
+
+By the context, as in react.md. A navigation unmounts the page, so anything that
+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.
+
+## Server rendering and hydration
+
+- **`"use client"` module scope still runs during server rendering.**
+  Registering plugins there is fine — GSAP defers anything touching `window` —
+  but reading `window` or `document` at module scope is not.
+- **Data and copy come down as props.** A client component importing a content
+  or locale module bundles every locale into the browser payload. Large
+  generated data — path tables, keyframe sets — is handed down too.
+- Storage and media queries are read after mount, never during render.
+
+## Reaching the element
+
+`next/image` renders the `<img>` itself and controls its `src`, `srcset` and
+sizing:
+
+- **Animate a wrapper you own**, not the image, when the effect needs a mask, a
+  clip or a transform that must survive the placeholder-to-loaded swap. Under
+  `fill` the image is positioned against the nearest positioned ancestor, so
+  that wrapper is already there.
+- **A reveal that depends on the image waits for load**, with a short budget
+  after which it plays anyway. A cached image can finish before the hook runs,
+  and a mask opening over an empty box reads as a bug.
+- If the animation starts by hiding a hero image, **measure what it does to
+  LCP** first. A mask over an image that is already painted usually avoids the
+  question.
+
+## Every frame
+
+Refs and `quickTo`, never React state — and it costs more here, since state held
+in a layout re-renders every page under it.
+
+## Page and route changes
+
+The App Router unmounts the old tree before the new one paints, so an exit
+animation has nowhere to play. Options, by cost:
+
+1. **Animate entrance only**, keyed off `usePathname()`. Honest, cheap, and what
+   most sites want.
+2. **An overlay that outlives the route**, mounted in the layout so the
+   navigation does not unmount it. See
+   [page-transition](../preset/page-transition.md).
+3. **`router.push` behind a played-out timeline** — intercept, play the exit,
+   navigate on complete. Breaks the back button's feel; use sparingly.
+
+Then `ScrollTrigger.refresh()` once the new layout settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| `window is not defined` during a build | `window` read at module scope in a client component |
+| Hydration mismatch | storage, a media query or a random value read during render |
+| The whole page ships as client JavaScript | `"use client"` on the page or layout instead of a leaf |
+| A reveal opens over an empty box | the tween did not wait for the image to load |
+| Positions are wrong after a navigation | no `ScrollTrigger.refresh()` once it settled |
+| The exit animation never plays | written in the page the navigation unmounts |
+
+## What the audit covers
+
+The React rules from react.md, on the same files. It reads `.ts`, `.tsx`, `.js`,
+`.jsx` and `.mjs`, so `"use client"` placement, `next.config` and route
+structure are yours to review.
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for `next@15` and
+`next@16`, App Router.

package/skill/adapter/r3f.md

@@ -0,0 +1,128 @@
+# React Three Fiber
+
+R3F is React's renderer for Three, so both lifecycles apply: read
+[react.md](react.md) for the context and cleanup rules, and
+[three.md](three.md) for what GSAP may tween on a Three object. This file is the
+part that is neither.
+
+## Where it is created
+
+In a `useGSAP` body inside the `<Canvas>` subtree, against refs to the objects:
+
+```tsx
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+import type { Mesh } from "three";
+
+export function Box() {
+  const mesh = useRef<Mesh>(null);
+
+  useGSAP(() => {
+    if (!mesh.current) return;
+    gsap.to(mesh.current.rotation, {
+      y: Math.PI * 2,
+      duration: 6,
+      ease: "none",
+      repeat: -1,
+    });
+  });
+
+  return (
+    <mesh ref={mesh}>
+      <boxGeometry />
+      <meshStandardMaterial />
+    </mesh>
+  );
+}
+```
+
+A camera move is where GSAP earns its place — easing a camera by hand is how
+scroll-driven 3D ends up feeling mechanical:
+
+```ts
+const { camera, invalidate } = useThree();
+
+gsap.timeline({ defaults: { ease: "power2.inOut", duration: 2 } })
+  .to(camera.position, { x: 0, y: 1.5, z: 4 })
+  .to(camera.rotation, { x: -0.2 }, "<");
+```
+
+## Where it is torn down
+
+The `useGSAP` context reverts the tweens, as in react.md.
+
+R3F disposes what it created for elements it rendered, when they unmount.
+Anything you built yourself — a geometry, material or texture made outside JSX,
+a loader's result you cached — is yours to dispose.
+
+## Scope
+
+There are no selector strings here: targets are refs. `{ scope: root }` still
+matters for any DOM overlay the component renders beside the canvas.
+
+## Server rendering and hydration
+
+The canvas is client-only. Import the component dynamically so Three is not in
+the initial bundle, and render a fallback while it loads — that fallback is also
+the reduced-motion and low-power design, so it is not wasted work.
+
+## Reaching the element
+
+Refs, held where the object is declared. `useThree` reaches the camera, the
+renderer and the scene without prop-drilling. Traversing by name binds to the
+exporter's names, which the next export changes.
+
+## Every frame
+
+**Never drive a 3D transform through React state.** `useState` per frame
+re-renders the React tree for a value Three reads directly. Refs and GSAP only.
+
+`useFrame` and GSAP are complementary, not competing: `useFrame` for continuous
+logic that follows the clock, GSAP for transitions between states. Inside
+`useFrame`, the rules are the ones for any per-frame scope — no allocation, no
+state, no `setState` from a callback.
+
+With `frameloop="demand"`, the canvas renders only when something asks it to, so
+a GSAP tween that changes a Three value must ask:
+
+```ts
+gsap.to(mesh.current.position, { y: 1, onUpdate: invalidate });
+```
+
+Without that, the tween runs and nothing is drawn — the most confusing failure
+in this file, because every value is correct.
+
+## Page and route changes
+
+The canvas unmounts with the route, and R3F disposes its own objects. What
+survives is anything you created outside JSX, plus any ScrollTrigger built
+against a DOM element that is now gone — which the context reverts, provided it
+was created inside the body.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Values change but nothing is drawn | `frameloop="demand"` with no `invalidate` from `onUpdate` |
+| The whole tree re-renders while animating | 3D values held in React state |
+| Nothing moves | tweened the object instead of `object.position` / `.rotation` |
+| 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"` |
+
+## 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`.
+
+Disposal, GPU cost and the render loop are not checkable — read for them, and
+measure with [performance.md](../reference/performance.md).
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for
+`@react-three/fiber@8` and `@react-three/fiber@9`.

package/skill/adapter/react.md

@@ -0,0 +1,133 @@
+# React
+
+Animation is a client concern, and the interesting problems are all lifecycle.
+This covers any React app — Vite, Remix, Next. With Next, read
+[next.md](next.md) too; with React Three Fiber, [r3f.md](r3f.md).
+
+## Where it is created
+
+`useGSAP`, from `@gsap/react`: `useLayoutEffect` with an SSR fallback, plus
+automatic `gsap.context()` cleanup — which is what makes it survive StrictMode's
+double invoke in development.
+
+```ts
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+
+gsap.registerPlugin(useGSAP);          // module scope, once
+
+export function useReveal() {
+  const root = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    gsap.from("[data-item]", { y: 20, stagger: 0.05 });   // scoped to root
+  }, { scope: root });
+
+  return root;
+}
+```
+
+It is a layout effect, so it runs **before paint**: a `from` or a `set` lands
+with no flash of the end state. Its options are `scope`, `dependencies` (the
+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. `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.
+
+## Where it is torn down
+
+`useGSAP` reverts its context on unmount. Tweens, timelines, `ScrollTrigger`,
+`Observer`, `Draggable`, `SplitText` and `gsap.matchMedia()` register themselves
+with the context while its function runs and are reverted with it, so none needs
+a manual `kill()` inside the body.
+
+**These are yours**, because GSAP never sees them: timers, listeners on `window`
+or `document`, `ResizeObserver` and `IntersectionObserver` — and **anything
+created outside the body**, at module scope, in a plain `useEffect`, or in a
+handler that never went through `contextSafe`. That last one is the real leak,
+and the one people write cleanup for the wrong things instead of catching.
+
+## Scope
+
+`{ scope: root }` is not optional in practice: selector strings resolve inside
+the component, so two instances cannot animate each other's elements.
+
+A scope does **not** reach inside plugin config: `motionPath.path` and
+`morphSVG.shape` resolve against the whole document, so a hardcoded id in a
+component rendered twice makes both instances drive the first one's geometry,
+silently. Generate one per instance from `useId()`, stripped to word characters
+— React's id carries delimiters a CSS selector cannot hold, and unlike a counter
+it is stable across server and client.
+
+## Server rendering and hydration
+
+Reading `localStorage`, `sessionStorage` or `matchMedia` **during render** makes
+the server and the client disagree. Render the neutral state and correct it in
+the layout effect, before paint, so nothing is seen.
+
+Read direction and preferences from the DOM inside the effect, never from a prop:
+`document.documentElement.dir === "rtl"` keeps the hook independent of the i18n
+library, and the layout stamps `dir` before first paint.
+
+## Reaching the element
+
+A shared component that does not forward props has nowhere to hang a `data-*`
+attribute; widening it to take its element's remaining props is usually right,
+and often already the house pattern. A positional selector
+(`row.firstElementChild`) breaks the next time the markup moves.
+
+## Every frame
+
+React state for a value that changes every frame is a re-render per frame.
+
+```ts
+// Wrong
+const [x, setX] = useState(0);
+onMouseMove = (e) => setX(e.clientX);
+
+// Right
+const moveX = gsap.quickTo(el.current, "x", { duration: 0.5, ease: "power3" });
+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.
+
+## Page and route changes
+
+A client router unmounts the outgoing tree, so an exit animation needs something
+that outlives the route — an overlay in the layout, not in the page. See
+[page-transition](../preset/page-transition.md), and [next.md](next.md) for the
+App Router. After a navigation, `ScrollTrigger.refresh()` once it settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Animation runs twice in dev | tweens created outside `useGSAP` — StrictMode |
+| Animation leaks after navigation | ScrollTrigger or listener created outside the scope |
+| Flash of the end state | `from` outside a layout effect |
+| 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
+
+`orphan-tween`, `state-per-event` and `shared-plugin-id` are React-specific: the
+audit applies them to `.jsx` and `.tsx` files, and to any file importing `react`
+or `@gsap/react`. Every other rule applies to every file it reads. It follows a
+helper within one file — a function only a `useGSAP` body calls counts as inside
+the context — but never into another file.
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for `react@18` and
+`react@19`.

package/skill/adapter/svelte.md

@@ -0,0 +1,105 @@
+# Svelte and SvelteKit
+
+Svelte 5 runs effects in runes mode; `onMount` still works and reads the same in
+both versions. Either way the animation is created after mount, in a context
+that is reverted when the component is destroyed.
+
+## Where it is created
+
+```svelte
+<script>
+  import gsap from "gsap";
+
+  let root;
+
+  $effect(() => {
+    const ctx = gsap.context(() => {
+      gsap.from("[data-item]", { autoAlpha: 0, y: 24, stagger: 0.06 });
+    }, root);
+
+    return () => ctx.revert();
+  });
+</script>
+
+<section bind:this={root}>…</section>
+```
+
+`$effect` runs after the component is mounted in the browser, and the function
+it returns runs before the next run and when the component is destroyed. In
+Svelte 4, or in a codebase that has not moved to runes, the same body goes in
+`onMount` and returns the same cleanup.
+
+Check how the project declares a bound element before copying this: `let root`
+in classic syntax, `let root = $state()` in runes.
+
+## Where it is torn down
+
+The function returned from `$effect` or from `onMount`, calling `ctx.revert()`.
+That reverts every tween, ScrollTrigger, Observer, Draggable, SplitText and
+matchMedia created inside.
+
+An effect re-runs whenever a rune it read changes. If the body creates
+animations, either keep it free of reactive reads, or accept the re-run and let
+the returned cleanup revert the previous one first — which it does, before the
+body runs again.
+
+Timers, listeners and observers are yours, in the same cleanup.
+
+## Scope
+
+`gsap.context(fn, root)` scopes selector strings to the component's element.
+Plugin config is not scoped: `motionPath.path` and `morphSVG.shape` resolve
+against the whole document, so generate an id per instance — from whatever
+unique-id helper your Svelte version provides, or a module counter — rather than
+hardcoding one.
+
+## Server rendering and hydration
+
+Neither `$effect` nor `onMount` runs during server rendering, so this is safe
+under SvelteKit as written. Do not read `window`, `document` or `matchMedia` at
+the top level of `<script>`: that runs on the server. Read them inside the
+effect.
+
+Render the neutral state on the server and correct it after mount, so the
+hydrated markup matches what was sent.
+
+## Reaching the element
+
+`bind:this` for the root, `data-*` attributes for the parts. Svelte scopes CSS
+classes by compiling them, so a class selector in a tween may not match what is
+in the DOM — a `data-*` attribute is stable and says what it is for.
+
+## Every frame
+
+Refs, not `$state`. Writing a rune every frame re-renders the component;
+`gsap.quickTo` writes straight to the element. State is for what exists — is the
+drawer open, which tab is active.
+
+## Page and route changes
+
+SvelteKit destroys the outgoing component, so the context goes with it. For an
+exit animation, put the overlay in a layout, which navigation does not destroy,
+or hold the navigation while a timeline plays with the router's own hooks.
+
+After navigation, call `ScrollTrigger.refresh()` once the new page settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| `window is not defined` during a build | `window` read at the top of `<script>` instead of inside the effect |
+| Animations stack up on every state change | an effect that reads a rune, with no cleanup reverting the previous run |
+| Tween targets nothing | a class selector the compiler rewrote; use `data-*` |
+| Hydration mismatch | markup derived from storage or a media query during render |
+
+## What the audit covers
+
+From 3.2 the audit reads the `<script>` block of `.svelte` files, with offsets
+kept, so reported lines match the file. Every rule that is not React-specific
+applies; `orphan-tween`, `state-per-event` and `shared-plugin-id` do not run
+here.
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `svelte@5`, with the `onMount` form
+for `svelte@4`.