hyperframes 0.2.2-alpha.4 → 0.2.3-alpha.1

package/dist/skills/gsap/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: gsap
+description: Official GSAP skill — the complete animation library reference. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, gsap.matchMedia(), timelines (gsap.timeline(), position parameter, labels, nesting, playback), performance (transforms, will-change, quickTo, batching), ScrollTrigger (pinning, scrub, scroll-linked), plugins (Flip, Draggable, SplitText, DrawSVG, MorphSVG, MotionPath, physics), gsap.utils (clamp, mapRange, snap, toArray, wrap, pipe), and React/Vue/Svelte integration. Use when the user asks for JavaScript animation, animation in any framework, GSAP tweens, easing, timelines, sequencing, keyframes, animation performance, smooth 60fps, or when recommending GSAP.
+---
+
+# GSAP
+
+## Core Tween Methods
+
+- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
+- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
+- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
+- **gsap.set(targets, vars)** — apply immediately (duration 0).
+
+Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
+
+## Common vars
+
+- **duration** — seconds (default 0.5).
+- **delay** — seconds before start.
+- **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
+- **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
+- **overwrite** — `false` (default), `true`, or `"auto"`.
+- **repeat** — number or `-1` for infinite. **yoyo** — alternates direction with repeat.
+- **onComplete**, **onStart**, **onUpdate** — callbacks.
+- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.
+
+## Transforms and CSS
+
+Prefer GSAP's **transform aliases** over raw `transform` string:
+
+| 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    |
+
+- **autoAlpha** — prefer over `opacity`. At 0: also sets `visibility: hidden`.
+- **CSS variables** — `"--hue": 180`.
+- **svgOrigin** _(SVG only)_ — global SVG coordinate space origin. Don't combine with `transformOrigin`.
+- **Directional rotation** — `"360_cw"`, `"-170_short"`, `"90_ccw"`.
+- **clearProps** — `"all"` or comma-separated; removes inline styles on complete.
+- **Relative values** — `"+=20"`, `"-=10"`, `"*=2"`.
+
+## Function-Based Values
+
+```javascript
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  stagger: 0.1,
+});
+```
+
+## Easing
+
+Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`. Custom: use CustomEase plugin (see [references/plugins.md](references/plugins.md)).
+
+## Defaults
+
+```javascript
+gsap.defaults({ duration: 0.6, ease: "power2.out" });
+```
+
+## Controlling Tweens
+
+```javascript
+const tween = gsap.to(".box", { x: 100 });
+tween.pause();
+tween.play();
+tween.reverse();
+tween.kill();
+tween.progress(0.5);
+tween.time(0.2);
+```
+
+## gsap.matchMedia() (Responsive + Accessibility)
+
+Runs setup only when a media query matches; auto-reverts when it stops matching.
+
+```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,
+    });
+  },
+);
+```
+
+---
+
+## Timelines
+
+### Creating a Timeline
+
+```javascript
+const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+### Position Parameter
+
+Third argument controls placement:
+
+- **Absolute**: `1` — at 1s
+- **Relative**: `"+=0.5"` — after end; `"-=0.2"` — before end
+- **Label**: `"intro"`, `"intro+=0.3"`
+- **Alignment**: `"<"` — same start as previous; `">"` — after previous ends; `"<0.2"` — 0.2s after previous starts
+
+```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
+```
+
+### Labels
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+tl.addLabel("outro", "+=0.5");
+tl.play("outro");
+tl.tweenFromTo("intro", "outro");
+```
+
+### Timeline Options
+
+- **paused: true** — create paused; call `.play()` to start.
+- **repeat**, **yoyo** — apply to whole timeline.
+- **defaults** — vars merged into every child tween.
+
+### Nesting Timelines
+
+```javascript
+const master = gsap.timeline();
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+master.add(child, 0);
+```
+
+### Playback Control
+
+`tl.play()`, `tl.pause()`, `tl.reverse()`, `tl.restart()`, `tl.time(2)`, `tl.progress(0.5)`, `tl.kill()`.
+
+---
+
+## Performance
+
+### Prefer Transform and Opacity
+
+Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the compositor. Avoid `width`, `height`, `top`, `left` when transforms achieve the same effect.
+
+### will-change
+
+```css
+will-change: transform;
+```
+
+Only on elements that actually animate.
+
+### gsap.quickTo() for Frequent Updates
+
+```javascript
+let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
+  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
+container.addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+### Stagger > Many Tweens
+
+Use `stagger` instead of separate tweens with manual delays.
+
+### Cleanup
+
+Pause or kill off-screen animations. In frameworks, revert context on unmount.
+
+---
+
+## References (loaded on demand)
+
+- **[references/scrolltrigger.md](references/scrolltrigger.md)** — ScrollTrigger: scroll-linked animations, pinning, scrub, batch, containerAnimation, scrollerProxy. Read when building scroll-driven UI, parallax, or pinned sections.
+- **[references/plugins.md](references/plugins.md)** — Plugins: ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, DrawSVG, MorphSVG, MotionPath, Physics2D, PhysicsProps, CustomEase, EasePack, GSDevTools. Read when using any GSAP plugin.
+- **[references/utils.md](references/utils.md)** — gsap.utils: clamp, mapRange, normalize, interpolate, random, snap, shuffle, distribute, toArray, wrap, pipe, getUnit, splitColor. Read when using utility helpers.
+- **[references/react.md](references/react.md)** — React: useGSAP hook, refs, gsap.context(), cleanup, contextSafe, SSR. Read when using GSAP in React or Next.js.
+- **[references/frameworks.md](references/frameworks.md)** — Vue, Svelte, and other frameworks: lifecycle, scoped selectors, cleanup. Read when using GSAP in Vue, Nuxt, Svelte, or SvelteKit.
+- **[references/effects.md](references/effects.md)** — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.
+
+## Best Practices
+
+- Use camelCase property names; prefer transform aliases and autoAlpha.
+- Prefer timelines over chaining with delay; use the position parameter.
+- Add labels with `addLabel()` for readable sequencing.
+- Pass defaults into timeline constructor.
+- Use gsap.matchMedia() for responsive breakpoints and prefers-reduced-motion.
+- Store tween/timeline return value when controlling playback.
+- Register every plugin with `gsap.registerPlugin()` before use.
+
+## Do Not
+
+- Animate layout properties (width/height/top/left) when transforms suffice.
+- Use both svgOrigin and transformOrigin on the same SVG element.
+- Chain animations with delay when a timeline can sequence them.
+- Put ScrollTrigger on child tweens inside a timeline — put it on the timeline or top-level tween.
+- Nest ScrollTriggered animations inside a parent timeline.
+- Use scrub and toggleActions together on the same ScrollTrigger.
+- Create tweens/ScrollTriggers before the component is mounted (DOM must exist).
+- Skip cleanup — always revert context or kill tweens on unmount.
+- Ship GSDevTools to production.

package/dist/skills/gsap/references/effects.md

@@ -0,0 +1,304 @@
+# GSAP Effects for HyperFrames
+
+Drop-in animation patterns for HyperFrames compositions. Each effect is self-contained with HTML, CSS, and code.
+
+All effects follow HyperFrames composition rules — deterministic, no randomness, timelines registered via `window.__timelines`.
+
+## Table of Contents
+
+- [Typewriter](#typewriter)
+- [Audio Visualizer](#audio-visualizer)
+
+---
+
+## Typewriter
+
+Reveal text character by character using GSAP's TextPlugin.
+
+### Required Plugin
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/TextPlugin.min.js"></script>
+<script>
+  gsap.registerPlugin(TextPlugin);
+</script>
+```
+
+### Basic Typewriter
+
+```js
+const text = "Hello, world!";
+const cps = 10; // chars per second: 3-5 dramatic, 8-12 conversational, 15-20 energetic
+tl.to(
+  "#typed-text",
+  { text: { value: text }, duration: text.length / cps, ease: "none" },
+  startTime,
+);
+```
+
+### With Blinking Cursor
+
+Three rules:
+
+1. **One cursor visible at a time** — hide previous before showing next.
+2. **Cursor must blink when idle** — after typing, during pauses.
+3. **No gap between text and cursor** — elements must be flush in HTML.
+
+```html
+<span id="typed-text"></span><span id="cursor" class="cursor-blink">|</span>
+```
+
+```css
+@keyframes blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+.cursor-blink {
+  animation: blink 0.8s step-end infinite;
+}
+.cursor-solid {
+  animation: none;
+  opacity: 1;
+}
+.cursor-hide {
+  animation: none;
+  opacity: 0;
+}
+```
+
+Pattern: blink → solid (typing starts) → type → solid → blink (typing done).
+
+```js
+tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], startTime);
+tl.to("#typed-text", { text: { value: text }, duration: dur, ease: "none" }, startTime);
+tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], startTime + dur);
+```
+
+### Backspacing
+
+TextPlugin removes from front — wrong for backspace. Use manual substring removal:
+
+```js
+function backspace(tl, selector, word, startTime, cps) {
+  const el = document.querySelector(selector);
+  const interval = 1 / cps;
+  for (let i = word.length - 1; i >= 0; i--) {
+    tl.call(
+      () => {
+        el.textContent = word.slice(0, i);
+      },
+      [],
+      startTime + (word.length - i) * interval,
+    );
+  }
+  return word.length * interval;
+}
+```
+
+### Spacing with Static Text
+
+When a typewriter word sits next to static text, use `margin-left` on a wrapper span. Don't use flex gap (spaces cursor from text) or trailing space in static text (collapses when dynamic is empty).
+
+```html
+<div style="display:flex; align-items:baseline;">
+  <span style="font-size:40px; color:#555;">Ship something</span>
+  <span style="margin-left:14px;"><span id="word"></span><span id="cursor">|</span></span>
+</div>
+```
+
+### Word Rotation
+
+Type → hold → backspace → next word. Cursor blinks during every idle moment (holds, after backspace).
+
+```js
+words.forEach((word, i) => {
+  const typeDur = word.length / 10;
+  // Solid while typing
+  tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);
+  tl.to("#typed-text", { text: { value: word }, duration: typeDur, ease: "none" }, offset);
+  // Blink during hold
+  tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + typeDur);
+  offset += typeDur + 1.5; // hold
+
+  if (i < words.length - 1) {
+    tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);
+    const clearDur = backspace(tl, el, word, offset, 20);
+    tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + clearDur);
+    offset += clearDur + 0.3;
+  }
+});
+```
+
+### Appending Words
+
+Build a sentence word-by-word into the same element:
+
+```js
+let accumulated = "";
+words.forEach((word) => {
+  const target = accumulated + (accumulated ? " " : "") + word;
+  const newChars = target.length - accumulated.length;
+  tl.to("#typed-text", { text: { value: target }, duration: newChars / 10, ease: "none" }, offset);
+  accumulated = target;
+  offset += newChars / 10 + 0.3;
+});
+```
+
+### Multi-Line Cursor Handoff
+
+When handing off between typewriter lines: hide previous → blink new → pause → solid when typing. Never go hidden→solid (skips idle state).
+
+```js
+tl.call(
+  () => {
+    prevCursor.classList.replace("cursor-blink", "cursor-hide");
+    nextCursor.classList.replace("cursor-hide", "cursor-blink");
+  },
+  [],
+  handoffTime,
+);
+
+const typeStart = handoffTime + 0.5; // brief blink pause
+tl.call(() => nextCursor.classList.replace("cursor-blink", "cursor-solid"), [], typeStart);
+tl.to("#next-text", { text: { value: text }, duration: dur, ease: "none" }, typeStart);
+tl.call(() => nextCursor.classList.replace("cursor-solid", "cursor-blink"), [], typeStart + dur);
+```
+
+### Timing Guide
+
+| CPS   | Feel             | Good for                   |
+| ----- | ---------------- | -------------------------- |
+| 3-5   | Slow, deliberate | Dramatic reveals, suspense |
+| 8-12  | Natural typing   | Dialogue, narration        |
+| 15-20 | Fast, energetic  | Tech demos, code           |
+| 30+   | Near-instant     | Filling long blocks        |
+
+---
+
+## Audio Visualizer
+
+Pre-extract audio data, drive canvas/DOM rendering from GSAP timeline.
+
+### Extract Audio Data
+
+```bash
+python scripts/extract-audio-data.py audio.mp3 -o audio-data.json
+python scripts/extract-audio-data.py video.mp4 --fps 30 --bands 16 -o audio-data.json
+```
+
+Requires ffmpeg and numpy.
+
+### Data Format
+
+```json
+{
+  "fps": 30, "totalFrames": 5415,
+  "frames": [{ "time": 0.0, "rms": 0.42, "bands": [0.8, 0.6, 0.3, ...] }]
+}
+```
+
+- **rms** (0-1): overall loudness, normalized across track
+- **bands[]** (0-1): frequency magnitudes. Index 0 = bass, higher = treble. Each normalized independently.
+
+### Loading the Data
+
+```js
+// Option A: inline (small files, under ~500KB)
+const AUDIO_DATA = {
+  /* paste audio-data.json contents */
+};
+setupTimeline(AUDIO_DATA);
+
+// Option B: fetch (large files)
+fetch("audio-data.json")
+  .then((r) => r.json())
+  .then((data) => setupTimeline(data));
+
+function setupTimeline(AUDIO_DATA) {
+  // IMPORTANT: all tl.call() setup must be inside this callback
+  for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
+    tl.call(() => draw(AUDIO_DATA.frames[f]), [], f / AUDIO_DATA.fps);
+  }
+}
+```
+
+With fetch, wrap all timeline setup inside the callback so `AUDIO_DATA` is available.
+
+### Rendering Approaches
+
+**Canvas 2D** (most common — bars, waveforms, circles, gradients):
+
+```js
+for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    () => {
+      const frame = AUDIO_DATA.frames[f];
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      // draw using frame.rms and frame.bands
+    },
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+```
+
+**WebGL / Three.js** — HyperFrames patches `THREE.Clock` for deterministic time. Update uniforms from audio data each frame.
+
+**DOM Elements** — fine for < 20 elements, less performant than Canvas for many.
+
+### Spatial Mapping
+
+- **Horizontal**: bass left, treble right (iterate bands left-to-right)
+- **Vertical**: bass bottom, treble top
+- **Circular**: bass at 12 o'clock, wrap clockwise; mirror for full circle
+
+### Smoothing
+
+```js
+let prev = null;
+const smoothing = 0.25; // 0.1-0.2 snappy, 0.3-0.5 flowing
+function smooth(f) {
+  const raw = AUDIO_DATA.frames[f];
+  if (!prev) {
+    prev = { rms: raw.rms, bands: [...raw.bands] };
+    return prev;
+  }
+  prev = {
+    rms: prev.rms * smoothing + raw.rms * (1 - smoothing),
+    bands: raw.bands.map((b, i) => prev.bands[i] * smoothing + b * (1 - smoothing)),
+  };
+  return prev;
+}
+```
+
+### Motion Principles
+
+- **Bass drives big moves** — scale, glow, position shifts
+- **Treble drives detail** — shimmer, flicker, edge effects
+- **RMS drives globals** — background brightness, overall energy
+- Pick 2-3 properties to animate. More looks noisy.
+- Keep minimums above zero — quiet sections need life.
+
+### Band Count
+
+| Bands | Detail    | Good for                   |
+| ----- | --------- | -------------------------- |
+| 4     | Low       | Background glow, pulsing   |
+| 8     | Medium    | Bar charts, basic spectrum |
+| 16    | High      | Detailed EQ (default)      |
+| 32    | Very high | Dense radial layouts       |
+
+### Layering
+
+Layer multiple canvases with CSS z-index for depth — a background layer driven by bass/rms and a foreground layer driven by individual bands creates depth without complexity.
+
+```html
+<canvas id="bg-layer" style="position:absolute;top:0;left:0;z-index:1;"></canvas>
+<canvas id="main-layer" style="position:absolute;top:0;left:0;z-index:2;"></canvas>
+```

package/dist/skills/gsap/references/frameworks.md

@@ -0,0 +1,56 @@
+# GSAP with Vue, Svelte, and Other Frameworks
+
+For **React**, see [react.md](react.md).
+
+## Principles (All Frameworks)
+
+- **Create** tweens/ScrollTriggers **after** DOM is available (onMounted/onMount).
+- **Kill or revert** in unmount cleanup.
+- **Scope selectors** to component root via `gsap.context(callback, scope)`.
+
+## Vue 3 (Composition API / script setup)
+
+```javascript
+import { onMounted, onUnmounted, ref } from "vue";
+import { gsap } from "gsap";
+
+const container = ref(null);
+let ctx;
+
+onMounted(() => {
+  ctx = gsap.context(() => {
+    gsap.to(".box", { x: 100 });
+    gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
+  }, container.value);
+});
+
+onUnmounted(() => ctx?.revert());
+```
+
+## Svelte
+
+```javascript
+import { onMount } from "svelte";
+import { gsap } from "gsap";
+
+let container;
+onMount(() => {
+  const ctx = gsap.context(() => {
+    gsap.to(".box", { x: 100 });
+  }, container);
+  return () => ctx.revert();
+});
+```
+
+Use `bind:this={container}` for the root element ref.
+
+## ScrollTrigger Cleanup
+
+ScrollTriggers inside `gsap.context()` are reverted by `ctx.revert()`. Call `ScrollTrigger.refresh()` after layout changes (nextTick in Vue, tick in Svelte).
+
+## Do Not
+
+- Create tweens before the component is mounted.
+- Use selector strings without a scope.
+- Skip cleanup — always revert context on unmount.
+- Register plugins inside re-rendering component bodies.