takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/hyperframes-animation/adapters/gsap-easing-and-stagger.md

@@ -1,118 +1,118 @@
-# Easing, Stagger, and Function-Based Values
-
-## Easing
-
-Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`, `none`.
-
-Each has `.in`, `.out`, `.inOut` variants.
-
-| Ease                       | Use for                                                                 |
-| -------------------------- | ----------------------------------------------------------------------- |
-| `power1.out`, `power2.out` | Standard UI motion. Default for most entrances.                         |
-| `power3.out`, `power4.out` | Punchier deceleration. Title cards, hero reveals.                       |
-| `sine.inOut`               | Long, slow, calm motion. Crossfades, ambient drift.                     |
-| `back.out(1.7)`            | Slight overshoot. Playful entrances. The arg controls overshoot amount. |
-| `elastic.out(1, 0.3)`      | Springy bounce. First arg = amplitude, second = period.                 |
-| `expo.inOut`               | Snappy, dramatic. Quick transitions between hero scenes.                |
-| `none` (linear)            | Camera moves with timed counterpoint, mechanical motion.                |
-
-Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
-
-## Easing Vocabulary (character & mood)
-
-Easings are tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging. Every composition should use at least 3 different easings — `power2.out` for everything produces flat, monotonous motion.
-
-The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
-
-| Family               | Character                                                                    | Typical use                                                                                        |
-| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. power2 is the workhorse, power4 for dramatic snaps                                |
-| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Logo reveals, badge pops, card entrances. `back.out(2.5)` for playful, `back.out(1.2)` for elegant |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Panel scatter, energetic drops, fun reveals                                                        |
-| `bounce`             | Ball-drop bouncing                                                           | Physical interactions, icons landing, score counters                                               |
-| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                         |
-| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                 |
-| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                    |
-| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                              |
-
-**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical. The storyboard's mood description should guide which character fits — not a formula.
-
-## Defaults
-
-```javascript
-const tl = gsap.timeline({
-  paused: true,
-  defaults: { duration: 0.6, ease: "power2.out" },
-});
-```
-
-Or globally:
-
-```javascript
-gsap.defaults({ duration: 0.6, ease: "power2.out" });
-```
-
-Setting defaults at timeline scope is preferred — it documents the motion language of that composition in one place.
-
-## Stagger
-
-```javascript
-gsap.fromTo(".item", { y: 24, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, stagger: 0.08 });
-```
-
-Object form:
-
-```javascript
-gsap.fromTo(
-  ".item",
-  { y: 24, opacity: 0 },
-  {
-    y: 0,
-    opacity: 1,
-    stagger: {
-      each: 0.08, // delay between each
-      from: "center", // "start" | "end" | "center" | "edges" | "random" | index
-      amount: 0.6, // total stagger time (overrides each if both set)
-      grid: "auto", // for 2D stagger
-      axis: "x" | "y",
-    },
-  },
-);
-```
-
-Prefer `stagger` over N separate tweens with manual delays — it stays correct when the target count or order changes. Use `fromTo()` rather than `from()` so the start state is explicit (see `gsap-timeline-and-labels.md` → sub-composition entrances).
-
-## Function-Based Values
-
-Any var can be a function `(index, target, targets) => value`:
-
-```javascript
-gsap.to(".item", {
-  x: (i, target, targets) => i * 50,
-  rotation: (i) => (i % 2 === 0 ? 5 : -5),
-  stagger: 0.1,
-});
-```
-
-Use this for per-element values that depend on index, attributes, or measured size. Cheaper and more idiomatic than building tweens in a loop.
-
-## gsap.matchMedia (preview only)
-
-`matchMedia` runs setup only when a media query matches and auto-reverts when it stops matching. It is useful for **preview** in the browser at different viewport sizes, and for `prefers-reduced-motion`. It is **not** a substitute for rendering at the composition's actual `data-width`/`data-height` — HyperFrames renders at a fixed viewport.
-
-```javascript
-let mm = gsap.matchMedia();
-mm.add(
-  {
-    isDesktop: "(min-width: 800px)",
-    reduceMotion: "(prefers-reduced-motion: reduce)",
-  },
-  (context) => {
-    const { isDesktop, reduceMotion } = context.conditions;
-    gsap.to(".box", {
-      rotation: isDesktop ? 360 : 180,
-      duration: reduceMotion ? 0 : 2,
-    });
-  },
-);
-```
+# Easing, Stagger, and Function-Based Values
+
+## Easing
+
+Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`, `none`.
+
+Each has `.in`, `.out`, `.inOut` variants.
+
+| Ease                       | Use for                                                                 |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `power1.out`, `power2.out` | Standard UI motion. Default for most entrances.                         |
+| `power3.out`, `power4.out` | Punchier deceleration. Title cards, hero reveals.                       |
+| `sine.inOut`               | Long, slow, calm motion. Crossfades, ambient drift.                     |
+| `back.out(1.7)`            | Slight overshoot. Playful entrances. The arg controls overshoot amount. |
+| `elastic.out(1, 0.3)`      | Springy bounce. First arg = amplitude, second = period.                 |
+| `expo.inOut`               | Snappy, dramatic. Quick transitions between hero scenes.                |
+| `none` (linear)            | Camera moves with timed counterpoint, mechanical motion.                |
+
+Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
+
+## Easing Vocabulary (character & mood)
+
+Easings are tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging. Every composition should use at least 3 different easings — `power2.out` for everything produces flat, monotonous motion.
+
+The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
+
+| Family               | Character                                                                    | Typical use                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. power2 is the workhorse, power4 for dramatic snaps                                |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Logo reveals, badge pops, card entrances. `back.out(2.5)` for playful, `back.out(1.2)` for elegant |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Panel scatter, energetic drops, fun reveals                                                        |
+| `bounce`             | Ball-drop bouncing                                                           | Physical interactions, icons landing, score counters                                               |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                         |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                 |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                    |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                              |
+
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical. The storyboard's mood description should guide which character fits — not a formula.
+
+## Defaults
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.6, ease: "power2.out" },
+});
+```
+
+Or globally:
+
+```javascript
+gsap.defaults({ duration: 0.6, ease: "power2.out" });
+```
+
+Setting defaults at timeline scope is preferred — it documents the motion language of that composition in one place.
+
+## Stagger
+
+```javascript
+gsap.fromTo(".item", { y: 24, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, stagger: 0.08 });
+```
+
+Object form:
+
+```javascript
+gsap.fromTo(
+  ".item",
+  { y: 24, opacity: 0 },
+  {
+    y: 0,
+    opacity: 1,
+    stagger: {
+      each: 0.08, // delay between each
+      from: "center", // "start" | "end" | "center" | "edges" | "random" | index
+      amount: 0.6, // total stagger time (overrides each if both set)
+      grid: "auto", // for 2D stagger
+      axis: "x" | "y",
+    },
+  },
+);
+```
+
+Prefer `stagger` over N separate tweens with manual delays — it stays correct when the target count or order changes. Use `fromTo()` rather than `from()` so the start state is explicit (see `gsap-timeline-and-labels.md` → sub-composition entrances).
+
+## Function-Based Values
+
+Any var can be a function `(index, target, targets) => value`:
+
+```javascript
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  rotation: (i) => (i % 2 === 0 ? 5 : -5),
+  stagger: 0.1,
+});
+```
+
+Use this for per-element values that depend on index, attributes, or measured size. Cheaper and more idiomatic than building tweens in a loop.
+
+## gsap.matchMedia (preview only)
+
+`matchMedia` runs setup only when a media query matches and auto-reverts when it stops matching. It is useful for **preview** in the browser at different viewport sizes, and for `prefers-reduced-motion`. It is **not** a substitute for rendering at the composition's actual `data-width`/`data-height` — HyperFrames renders at a fixed viewport.
+
+```javascript
+let mm = gsap.matchMedia();
+mm.add(
+  {
+    isDesktop: "(min-width: 800px)",
+    reduceMotion: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { isDesktop, reduceMotion } = context.conditions;
+    gsap.to(".box", {
+      rotation: isDesktop ? 360 : 180,
+      duration: reduceMotion ? 0 : 2,
+    });
+  },
+);
+```

package/assets/.agent/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.md

@@ -1,96 +1,96 @@
-# Timelines and Labels
-
-HyperFrames is a seek-driven runtime. Build one paused timeline per composition, attach it to `window.__timelines["<composition-id>"]`, and let HyperFrames seek it. Never call `.play()` for render-critical motion.
-
-## Creating a Timeline
-
-```javascript
-const tl = gsap.timeline({
-  paused: true,
-  defaults: { duration: 0.5, ease: "power2.out" },
-});
-
-tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
-```
-
-Timeline options:
-
-- **paused: true** — required in HyperFrames. The framework drives the playhead.
-- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` is forbidden; use finite counts.
-- **defaults** — vars merged into every child tween. Use this instead of repeating `ease` and `duration` on every line.
-
-## Position Parameter
-
-The third argument to `.to()`/`.from()`/`.fromTo()` controls placement on the timeline:
-
-| Form           | Meaning                              |
-| -------------- | ------------------------------------ |
-| `0`, `1.5`     | Absolute time in seconds             |
-| `"+=0.5"`      | 0.5s after the end of the timeline   |
-| `"-=0.2"`      | 0.2s before the end of the timeline  |
-| `"intro"`      | At the `intro` label                 |
-| `"intro+=0.3"` | 0.3s after the `intro` label         |
-| `"<"`          | Same start as the previous tween     |
-| `">"`          | Right after the previous tween ends  |
-| `"<0.2"`       | 0.2s after the previous tween starts |
-| `">-0.1"`      | 0.1s before the previous tween ends  |
-
-```javascript
-tl.to(".a", { x: 100 }, 0);
-tl.to(".b", { y: 50 }, "<"); // same start as .a
-tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts
-```
-
-Prefer the position parameter over `delay:` — it composes naturally and survives refactors that re-order tweens.
-
-## Labels
-
-```javascript
-tl.addLabel("intro", 0);
-tl.to(".a", { x: 100 }, "intro");
-
-tl.addLabel("outro", "+=0.5");
-tl.to(".a", { opacity: 0 }, "outro");
-```
-
-Labels make a long timeline readable and let multiple tweens converge on the same beat without re-typing absolute times.
-
-## Nesting Timelines
-
-```javascript
-const master = gsap.timeline({ paused: true });
-
-const child = gsap.timeline();
-child.to(".a", { x: 100 }).to(".b", { y: 50 });
-
-master.add(child, 0);
-```
-
-In HyperFrames, **do not** nest sub-composition timelines into the host. Sub-compositions loaded via `data-composition-src` are seeked independently by HyperFrames from their own `data-start`. Nesting is only for grouping pieces of the _same_ composition's timeline.
-
-## Inside Sub-Compositions: prefer `fromTo` over `from`
-
-For entrance tweens inside a sub-composition, prefer `gsap.fromTo()` over `gsap.from()`:
-
-```javascript
-// Sub-composition entrance — survives re-seek cleanly
-tl.fromTo(".title", { y: 60, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0.2);
-```
-
-Why: HyperFrames re-seeks the sub-composition every time its host clip becomes visible. `gsap.from()` snapshots the starting state at **registration time** (page load); when the playhead jumps back past `data-start`, that snapshot can desync from the actual CSS state and the element renders in the wrong position. `gsap.fromTo()` declares both endpoints explicitly, so the seek-back always produces the same start state.
-
-In top-level (standalone) compositions either form works — there's no re-seek-through-mount cycle.
-
-## Playback Control (debug / preview only)
-
-```javascript
-tl.play();
-tl.pause();
-tl.reverse();
-tl.restart();
-tl.time(2);
-tl.progress(0.5);
-tl.kill();
-```
-
-These are useful when previewing in the browser. In rendered output HyperFrames calls `seek()` internally — your timeline must produce identical state for the same time value every time it is seeked.
+# Timelines and Labels
+
+HyperFrames is a seek-driven runtime. Build one paused timeline per composition, attach it to `window.__timelines["<composition-id>"]`, and let HyperFrames seek it. Never call `.play()` for render-critical motion.
+
+## Creating a Timeline
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.5, ease: "power2.out" },
+});
+
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+Timeline options:
+
+- **paused: true** — required in HyperFrames. The framework drives the playhead.
+- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` is forbidden; use finite counts.
+- **defaults** — vars merged into every child tween. Use this instead of repeating `ease` and `duration` on every line.
+
+## Position Parameter
+
+The third argument to `.to()`/`.from()`/`.fromTo()` controls placement on the timeline:
+
+| Form           | Meaning                              |
+| -------------- | ------------------------------------ |
+| `0`, `1.5`     | Absolute time in seconds             |
+| `"+=0.5"`      | 0.5s after the end of the timeline   |
+| `"-=0.2"`      | 0.2s before the end of the timeline  |
+| `"intro"`      | At the `intro` label                 |
+| `"intro+=0.3"` | 0.3s after the `intro` label         |
+| `"<"`          | Same start as the previous tween     |
+| `">"`          | Right after the previous tween ends  |
+| `"<0.2"`       | 0.2s after the previous tween starts |
+| `">-0.1"`      | 0.1s before the previous tween ends  |
+
+```javascript
+tl.to(".a", { x: 100 }, 0);
+tl.to(".b", { y: 50 }, "<"); // same start as .a
+tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts
+```
+
+Prefer the position parameter over `delay:` — it composes naturally and survives refactors that re-order tweens.
+
+## Labels
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+
+tl.addLabel("outro", "+=0.5");
+tl.to(".a", { opacity: 0 }, "outro");
+```
+
+Labels make a long timeline readable and let multiple tweens converge on the same beat without re-typing absolute times.
+
+## Nesting Timelines
+
+```javascript
+const master = gsap.timeline({ paused: true });
+
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+
+master.add(child, 0);
+```
+
+In HyperFrames, **do not** nest sub-composition timelines into the host. Sub-compositions loaded via `data-composition-src` are seeked independently by HyperFrames from their own `data-start`. Nesting is only for grouping pieces of the _same_ composition's timeline.
+
+## Inside Sub-Compositions: prefer `fromTo` over `from`
+
+For entrance tweens inside a sub-composition, prefer `gsap.fromTo()` over `gsap.from()`:
+
+```javascript
+// Sub-composition entrance — survives re-seek cleanly
+tl.fromTo(".title", { y: 60, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0.2);
+```
+
+Why: HyperFrames re-seeks the sub-composition every time its host clip becomes visible. `gsap.from()` snapshots the starting state at **registration time** (page load); when the playhead jumps back past `data-start`, that snapshot can desync from the actual CSS state and the element renders in the wrong position. `gsap.fromTo()` declares both endpoints explicitly, so the seek-back always produces the same start state.
+
+In top-level (standalone) compositions either form works — there's no re-seek-through-mount cycle.
+
+## Playback Control (debug / preview only)
+
+```javascript
+tl.play();
+tl.pause();
+tl.reverse();
+tl.restart();
+tl.time(2);
+tl.progress(0.5);
+tl.kill();
+```
+
+These are useful when previewing in the browser. In rendered output HyperFrames calls `seek()` internally — your timeline must produce identical state for the same time value every time it is seeked.

package/assets/.agent/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md

@@ -1,96 +1,96 @@
-# Transforms and Performance
-
-## Transform Aliases
-
-Prefer GSAP's transform aliases over raw `transform` strings:
-
-| GSAP property               | Equivalent            |
-| --------------------------- | --------------------- |
-| `x`, `y`, `z`               | `translateX/Y/Z` (px) |
-| `xPercent`, `yPercent`      | `translateX/Y` in `%` |
-| `scale`, `scaleX`, `scaleY` | `scale`               |
-| `rotation`                  | `rotate` (deg)        |
-| `rotationX`, `rotationY`    | 3D rotate             |
-| `skewX`, `skewY`            | `skew`                |
-| `transformOrigin`           | `transform-origin`    |
-
-Aliases let GSAP track and interpolate each axis independently, which prevents accidental overwrites between separate tweens on the same element.
-
-## autoAlpha
-
-Prefer `autoAlpha` over `opacity` for show/hide:
-
-```javascript
-gsap.to(".panel", { autoAlpha: 0, duration: 0.4 });
-```
-
-`autoAlpha: 0` sets both `opacity: 0` and `visibility: hidden`, which removes the element from hit-testing and accessibility tree at zero alpha — closer to "gone" than plain `opacity: 0`.
-
-## clearProps
-
-Removes inline styles set by GSAP when the tween completes:
-
-```javascript
-gsap.to(".item", { x: 100, rotation: 45, clearProps: "all" });
-gsap.to(".item", { x: 100, rotation: 45, clearProps: "rotation,x" });
-```
-
-Useful at the end of an animation segment to hand the element back to CSS.
-
-## CSS Variables
-
-```javascript
-gsap.to(".chart", { "--hue": 180, duration: 1 });
-```
-
-Animate any custom property. Works for color, length, number — anything CSS will interpolate.
-
-## Relative and Directional Values
-
-- Relative: `"+=20"`, `"-=10"`, `"*=2"`.
-- Directional rotation: `"360_cw"`, `"-170_short"`, `"90_ccw"` — controls which way the angle takes when going between two values.
-
-## SVG Specifics
-
-- `svgOrigin` sets transform origin in the SVG's global coordinate space (not the element's local box). **Do not** combine `svgOrigin` with `transformOrigin` on the same element — pick one.
-- Animate SVG transform attributes via the same alias names (`x`, `y`, `rotation`) — GSAP handles the SVG-specific quirks.
-
-## Performance Rules
-
-### Prefer transforms and opacity
-
-Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the GPU compositor. Avoid `width`, `height`, `top`, `left`, `margin`, `padding` when transforms achieve the same effect.
-
-### will-change (sparingly)
-
-```css
-.title {
-  will-change: transform;
-}
-```
-
-Only on elements that _actually_ animate. Applied everywhere it becomes useless and burns memory.
-
-### gsap.quickTo for frequent updates (preview-only)
-
-For high-frequency updates driven by **events** — pointer move, scroll, audio scrub — `quickTo` reuses the same tween instead of creating a new one each frame:
-
-```javascript
-const xTo = gsap.quickTo("#cursor", "x", { duration: 0.4, ease: "power3" });
-const yTo = gsap.quickTo("#cursor", "y", { duration: 0.4, ease: "power3" });
-
-container.addEventListener("mousemove", (e) => {
-  xTo(e.pageX);
-  yTo(e.pageY);
-});
-```
-
-> **Render mode has no input events.** The renderer seeks frame-by-frame; `mousemove`, `scroll`, etc. never fire. `quickTo`'s main use case applies in **live preview** in the browser only. For audio-reactive motion in renders, pre-extract audio data and drive the timeline declaratively (see `../rules/gsap-effects.md`).
-
-### Stagger beats N tweens
-
-One tween with `stagger` beats N tweens with manual delays for both readability and runtime cost.
-
-### Cleanup
-
-In live preview, pause or `kill()` off-screen animations. Render mode is unaffected (the renderer drives time directly).
+# Transforms and Performance
+
+## Transform Aliases
+
+Prefer GSAP's transform aliases over raw `transform` strings:
+
+| GSAP property               | Equivalent            |
+| --------------------------- | --------------------- |
+| `x`, `y`, `z`               | `translateX/Y/Z` (px) |
+| `xPercent`, `yPercent`      | `translateX/Y` in `%` |
+| `scale`, `scaleX`, `scaleY` | `scale`               |
+| `rotation`                  | `rotate` (deg)        |
+| `rotationX`, `rotationY`    | 3D rotate             |
+| `skewX`, `skewY`            | `skew`                |
+| `transformOrigin`           | `transform-origin`    |
+
+Aliases let GSAP track and interpolate each axis independently, which prevents accidental overwrites between separate tweens on the same element.
+
+## autoAlpha
+
+Prefer `autoAlpha` over `opacity` for show/hide:
+
+```javascript
+gsap.to(".panel", { autoAlpha: 0, duration: 0.4 });
+```
+
+`autoAlpha: 0` sets both `opacity: 0` and `visibility: hidden`, which removes the element from hit-testing and accessibility tree at zero alpha — closer to "gone" than plain `opacity: 0`.
+
+## clearProps
+
+Removes inline styles set by GSAP when the tween completes:
+
+```javascript
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "all" });
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "rotation,x" });
+```
+
+Useful at the end of an animation segment to hand the element back to CSS.
+
+## CSS Variables
+
+```javascript
+gsap.to(".chart", { "--hue": 180, duration: 1 });
+```
+
+Animate any custom property. Works for color, length, number — anything CSS will interpolate.
+
+## Relative and Directional Values
+
+- Relative: `"+=20"`, `"-=10"`, `"*=2"`.
+- Directional rotation: `"360_cw"`, `"-170_short"`, `"90_ccw"` — controls which way the angle takes when going between two values.
+
+## SVG Specifics
+
+- `svgOrigin` sets transform origin in the SVG's global coordinate space (not the element's local box). **Do not** combine `svgOrigin` with `transformOrigin` on the same element — pick one.
+- Animate SVG transform attributes via the same alias names (`x`, `y`, `rotation`) — GSAP handles the SVG-specific quirks.
+
+## Performance Rules
+
+### Prefer transforms and opacity
+
+Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the GPU compositor. Avoid `width`, `height`, `top`, `left`, `margin`, `padding` when transforms achieve the same effect.
+
+### will-change (sparingly)
+
+```css
+.title {
+  will-change: transform;
+}
+```
+
+Only on elements that _actually_ animate. Applied everywhere it becomes useless and burns memory.
+
+### gsap.quickTo for frequent updates (preview-only)
+
+For high-frequency updates driven by **events** — pointer move, scroll, audio scrub — `quickTo` reuses the same tween instead of creating a new one each frame:
+
+```javascript
+const xTo = gsap.quickTo("#cursor", "x", { duration: 0.4, ease: "power3" });
+const yTo = gsap.quickTo("#cursor", "y", { duration: 0.4, ease: "power3" });
+
+container.addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+> **Render mode has no input events.** The renderer seeks frame-by-frame; `mousemove`, `scroll`, etc. never fire. `quickTo`'s main use case applies in **live preview** in the browser only. For audio-reactive motion in renders, pre-extract audio data and drive the timeline declaratively (see `../rules/gsap-effects.md`).
+
+### Stagger beats N tweens
+
+One tween with `stagger` beats N tweens with manual delays for both readability and runtime cost.
+
+### Cleanup
+
+In live preview, pause or `kill()` off-screen animations. Render mode is unaffected (the renderer drives time directly).