dsh-hyperframes 0.9.1 → 0.9.3

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

@@ -1,199 +0,0 @@
-# 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`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default. |
-| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                            |
-| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                             |
-| `back.out(1.7)`                            | Overshoot then settle. RARE — explicitly-playful register only, never a default.                |
-| `elastic.out(1, 0.3)`                      | Springy bounce. Same playful-only rule; prefer a baked spring (see Spring Eases below).         |
-| `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.
-
-**Smooth beats bouncy** — the motion doctrine (`rules/spring-pop-entrance.md`, the workflows' `motion-language.md`): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`) are a rare, explicitly-playful register, never the house style.
-
-## 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. A composition should draw on ~3 easing characters across its beats — but vary **within the smooth families by energy** (`sine` / `power1` calm → `power3` standard → `power4` / `expo` punch); don't reach for overshoot to add variety. Overshoot is a _register_ (explicitly playful), not a spice. One ease everywhere reads flat; bounce everywhere reads cheap — the second failure is worse.
-
-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. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
-| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | RARE — explicitly-playful register only, never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
-| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | RARE — same playful-only rule; the baked spring (below) is the physical version                                                              |
-| `bounce`             | Ball-drop bouncing                                                           | RARE — physical-comedy register only (something literally dropping)                                                                          |
-| `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 — but bouncy is a register, not an emphasis tool; reach for it only on explicitly-playful beats. 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: "power3.out" }, // the house settle — smooth beats bouncy
-});
-```
-
-Or globally:
-
-```javascript
-gsap.defaults({ duration: 0.6, ease: "power3.out" });
-```
-
-Setting defaults at timeline scope is preferred — it documents the motion language of that composition in one place.
-
-## Spring Eases (baked physics, seek-safe)
-
-The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for the rare playful register — bake the spring's closed-form solution into a function ease.
-
-Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
-
-```javascript
-// springEase — a damped spring's exact position curve as a GSAP ease.
-// response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
-// dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
-//                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
-//                  0.60–0.70 = explicitly playful — ~5–10% overshoot (rare; replaces back.out)
-function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
-  const w = (2 * Math.PI) / response; // undamped natural frequency
-  const z = dampingFraction;
-  let pos; // x(t): 0 → 1, starting at rest (v0 = 0)
-  if (z < 1) {
-    const wd = w * Math.sqrt(1 - z * z);
-    pos = (t) => 1 - Math.exp(-z * w * t) * (Math.cos(wd * t) + ((z * w) / wd) * Math.sin(wd * t));
-  } else if (z > 1) {
-    const wo = w * Math.sqrt(z * z - 1);
-    pos = (t) =>
-      1 - Math.exp(-z * w * t) * (Math.cosh(wo * t) + ((z * w) / wo) * Math.sinh(wo * t));
-  } else {
-    pos = (t) => 1 - Math.exp(-w * t) * (1 + w * t);
-  }
-  // Settle time: last moment the curve sits outside ±0.1% of target.
-  // Fixed-step scan, runs once at setup — deterministic (no Math.random / Date.now).
-  const EPS = 0.001;
-  const rate = z <= 1 ? z * w : (z - Math.sqrt(z * z - 1)) * w; // slowest decay mode
-  const SCAN = 12 / rate;
-  const N = 4800;
-  let T = SCAN;
-  for (let i = N; i >= 0; i--) {
-    const t = (i / N) * SCAN;
-    if (Math.abs(1 - pos(t)) > EPS) {
-      T = ((i + 1) / N) * SCAN;
-      break;
-    }
-  }
-  const xT = pos(T);
-  return {
-    duration: T, // use as the tween's duration — the settle time IS the physics
-    ease: (p) => pos(p * T) + p * (1 - xT), // normalized so ease(1) === 1 exactly
-  };
-}
-```
-
-Usage — take **both** the ease and the duration from the helper (the settle time is part of the physics; overriding the duration just re-times the same curve, so tune speed via `response` instead):
-
-```javascript
-const settle = springEase({ response: 0.4 }); // critically damped → duration ≈ 0.59s
-tl.fromTo(
-  "#hero",
-  { scale: 0, opacity: 0 },
-  { scale: 1, opacity: 1, duration: settle.duration, ease: settle.ease },
-  0.2,
-);
-```
-
-| dampingFraction   | overshoot       | register                                                                                                                                           |
-| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
-| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
-| 0.60–0.70         | ~5–10%          | Explicitly-playful ONLY (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
-| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
-
-| response  | duration (ζ=1) | feel                                                         |
-| --------- | -------------- | ------------------------------------------------------------ |
-| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
-| 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
-| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — check the `t ≤ 0.5s` visibility rule |
-
-Craft notes:
-
-- **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
-- **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
-- **Doctrine unchanged**: ζ below ~0.8 is still the rare, explicitly-playful exception (`rules/spring-pop-entrance.md`). The default of this section is ζ=1 — real spring physics is not a license for bounce.
-
-## 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/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.md

@@ -1,96 +0,0 @@
-# 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: "power3.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/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md

@@ -1,129 +0,0 @@
-# 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`. The registered seekable timeline still interpolates only opacity; visibility changes at the hidden endpoint. Use `autoAlpha` only on non-clip elements or wrappers inside a clip; HyperFrames owns `.clip` visibility. Never duration-tween raw `visibility` or `display`.
-
-## 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.
-- **Resolve SVG geometry before building center-based transforms.** `createElementNS` is supported, but a detached, hidden, or zero-size element may not expose usable geometry when GSAP resolves a percentage `transformOrigin`. Attach and size the SVG before constructing the timeline, use an explicit `svgOrigin` when you know the canvas coordinates, or draw animated geometry around local `(0,0)` inside a positioning `<g>` for a center pivot that does not depend on a measured bounding box.
-
-## Performance Rules
-
-### Animate transforms, not layout properties
-
-Animate `x`, `y`, `scale`, `rotation`, `opacity`. Never animate `left`, `right`, `top`, `bottom`, `width`, `height`, `margin*`, the text-reflow props `letterSpacing` / `wordSpacing` / `fontSize` — and never `roundProps`.
-
-This is a **render-correctness** rule in HyperFrames, not just a GPU-performance nicety. The renderer seeks frame-by-frame and screenshots each frame, and the browser compositor snaps layout properties to whole device pixels. On a fast tween the per-frame step is several pixels, so the snap is invisible; on a slow tween or a long ease-out tail the value moves less than a pixel per frame — it holds the same pixel for several frames, then jumps a whole one. The result is motion that looks smooth when fast but visibly stutters when slow. Transforms interpolate sub-pixel and stay smooth at any speed. `roundProps` forces the same integer snap onto a transform — don't use it.
-
-"Layout property" is broader than position: anything that triggers **reflow** snaps the same way. `letterSpacing` / `fontSize` are the common trap — a slow "settle" that crawls one of them by a fraction of a pixel per frame dwells on a handful of discrete glyph layouts (visible micro-stutter). The faithful smooth fix depends on which property — **do not reach for `scale` reflexively**:
-
-- **`fontSize`** → animate `scale`. Scaling text up/down is the same visual and stays sub-pixel smooth (no reflow).
-- **`letterSpacing` / `wordSpacing`** → uniform `scale` is **not** the same effect (it resizes the glyphs; it does not change the gaps between them). To animate spacing smoothly, split the text into per-character (or per-word) elements and animate each one's `x` — the glyph spread is a transform, sub-pixel smooth and visually identical to a letter-spacing tween. GSAP's `SplitText` does the split. If the spacing change is a minor flourish, hold the final value statically instead.
-
-Unlike positional props, reflow props snap during browser **layout** — upstream of the canvas raster — so they stutter even in html-in-canvas, and the exception below does **not** apply to them.
-
-#### Fixing a flagged animation — preserve the intent
-
-The lint rule tells you a property will stutter; it does **not** tell you the fix, and a fix that merely passes lint can silently change the look. Swapping a `letterSpacing` tighten for a uniform `scale` lints clean but animates a _different thing_ (it resizes the glyphs instead of closing the gaps). Two rules:
-
-1. **Reproduce the same visual** — same start/end state, same trajectory, only sub-pixel-smooth. Use the faithful equivalent (per-glyph `x` for spacing, `scale` for `fontSize`, `x`/`y` for position), not whichever transform is the least code.
-2. **Verify against the original, not against the linter.** Render the original and the fixed version and compare the motion at its key moments — the fix should differ only by the removed stutter, not by _where things end up_. Lint-clean-and-smooth is not the bar; faithful-and-smooth is.
-
-If the faithful fix is non-trivial (a per-glyph split, a measured offset), build it or surface the tradeoff — never downgrade to a cheaper, different effect just to satisfy the linter.
-
-**Convert a position animation to a transform** by leaving the element at its resting `left`/`top` in CSS and animating the _offset_ with `x`/`y`:
-
-```javascript
-// CSS: #card { left: 1340px; top: 540px }   ← resting position stays in CSS
-tl.to("#card", { left: 1340, top: 540, duration: 1 }); // ✗ stutters
-tl.fromTo("#card", { x: 640, y: 0 }, { x: 0, y: 0, duration: 1 }); // ✓ x/y = delta from CSS rest (640 = startLeft − 1340)
-```
-
-For a parent-relative `left: "100%"` sweep, use `xPercent: 100` only when the element is the full width of its container; otherwise convert to pixels (`x: containerWidth`).
-
-**The one exception:** elements drawn through the html-in-canvas API — those under a `<canvas layoutsubtree>` ancestor, e.g. the `liquid-glass-*` blocks. The canvas rasterizes from sub-pixel `getComputedStyle`, so layout props don't snap there and those elements keep `left`/`top`. Everything the browser lays out (plain DOM) follows the rule.
-
-The `gsap_non_transform_motion` lint rule is the backstop, not the teacher — reach for transforms from the start instead of animating layout props and waiting for lint to reject them.
-
-### 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).

package/skills/hyperframes-animation/adapters/gsap.md

@@ -1,105 +0,0 @@
----
-name: hyperframes-gsap-adapter
-description: GSAP animation API reference for HyperFrames. Use when writing seekable GSAP timelines in HyperFrames compositions, including gsap.to(), from(), fromTo(), set(), timeline position parameters, labels, easing, stagger, finite repeats, and transform performance.
----
-
-# HyperFrames GSAP
-
-GSAP usage scoped to HyperFrames' seek-driven render model. This skill is the GSAP reference _as constrained by HyperFrames_ — for the framework's broader composition contract see `hyperframes-core`.
-
-## HyperFrames Contract
-
-HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-<script>
-  window.__timelines = window.__timelines || {};
-  const tl = gsap.timeline({ paused: true });
-
-  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
-  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
-
-  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
-</script>
-```
-
-- The registry key must match the composition root's `data-composition-id`.
-- Bracket and dot syntax both register: `window.__timelines["main"] = tl` and `window.__timelines.main = tl` are equivalent (the linter recognizes both). Bracket form is required when the id isn't a valid identifier (e.g. contains `-`).
-- Do not call `tl.play()` for render-critical motion.
-- Building inside an async callback such as `document.fonts.ready` is supported and common. What breaks is **registering the key before the build finishes**: an empty timeline registered early is treated as ready and nested empty, so it renders blank (`lint`: `gsap_timeline_registered_before_async_build`, error). Assign `window.__timelines[id] = tl` at the end of the callback. Do not drive render-critical motion from timers or event handlers.
-- Keep loops finite. HyperFrames renders finite video durations.
-- **Render duration comes from `data-duration` on the composition root, not from GSAP timeline length.** Do not pad the timeline with empty tweens like `tl.set({}, {}, 283)` to "extend" it. (Some external docs show this trick; in HyperFrames it conflicts with the seek-driven duration model — set `data-duration` instead.)
-
-## 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 (cheatsheet)
-
-- **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"`. See `./gsap-easing-and-stagger.md`.
-- **stagger** — number or object. See `./gsap-easing-and-stagger.md`.
-- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration.
-- **yoyo** — alternates direction with repeat.
-- **overwrite** — `false` (default), `true`, or `"auto"`.
-- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element.
-- **onComplete**, **onStart**, **onUpdate** — callbacks.
-
-For transforms, autoAlpha, clearProps, and SVG specifics see `./gsap-transforms-and-perf.md`.
-
-## Animated Property Allowlist
-
-HyperFrames is stricter than vanilla GSAP. Animate only:
-
-- **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
-- **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
-- **CSS variables**: `"--hue": 180` etc.
-- **Media `volume`** (on `<audio>` / `<video>`): do not tween it for fades or ducking; use the `data-automation` volume lane (`creator-editing-recipes.md` in `hyperframes-core`). A lane wins over a tween on the same element.
-- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Equivalent to the `onUpdate`-proxy form in `../rules/counting-dynamic-scale.md`; prefer that proxy form for locale formatting (`toLocaleString`) or suffix logic, and pair it with a separate transform-scale tween when the number should grow.
-
-**Avoid** (use the transform alias instead):
-
-- `width` / `height` / `top` / `left` / `right` / `bottom` / `margin*` / `padding*` — trigger layout reflows. Use `scaleX/Y` (with `transformOrigin`) or `x` / `y`.
-
-**Forbidden** (breaks the renderer or the clip lifecycle):
-
-- `display`, raw `visibility` **on a clip element**: never duration-tween these. HyperFrames owns a clip's visibility and `lint` rejects it. Use `autoAlpha` (opacity plus endpoint visibility) or a zero-duration timeline set at an explicit boundary. Animating a clip element's other visual properties is fine and the shipped catalog does it throughout; what is forbidden is taking over its visibility.
-- Anything driven by `Math.random()`, `Date.now()`, `performance.now()`, or event handlers — animation state must be deterministic from time alone.
-
-> **Note**: the list above is a **denylist**, not an allowlist. Properties outside it, including `width`, `height`, `filter`, `clipPath` and `strokeDashoffset`, are legitimate targets; prefer transforms and opacity where you have the choice, for performance rather than correctness. See `hyperframes-core/references/determinism-rules.md` for the full deterministic-render contract.
-
-## References
-
-- `./gsap-timeline-and-labels.md` — timeline creation, position parameter (`+=`, `<`, `>`), labels, nesting, sub-comp `fromTo` preference, playback control.
-- `./gsap-easing-and-stagger.md` — easing families, stagger objects, function-based values, `gsap.matchMedia()`, `gsap.defaults()`.
-- `./gsap-transforms-and-perf.md` — transform aliases, autoAlpha, `quickTo`, `will-change`, performance rules.
-- `../rules/gsap-effects.md` — drop-in recipes: typewriter (with cursor / backspace / word rotation) + audio visualizer (uses `skills/hyperframes-creative/scripts/extract-audio-data.py`).
-
-## Best Practices
-
-- Use camelCase property names; prefer transform aliases and autoAlpha.
-- Prefer timelines over chained tweens with delays; use the position parameter.
-- Add labels with `addLabel()` for readable sequencing.
-- Pass defaults into the timeline constructor.
-- Store the tween/timeline return value when controlling playback.
-
-## 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.
-- Create tweens before the DOM exists.
-- Use infinite `repeat: -1` in HyperFrames compositions — use finite repeat counts computed from the visible duration.
-
-## Credits And References
-
-- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.
-- GSAP documentation: https://gsap.com/docs/v3/
-- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/