first-commit

2026-05-04 14:58:14 -04:00
commit a46764fb1b
1210 changed files with 233231 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Audio-Reactive Animation
+
+Drive visuals from music, voice, or sound. Any GSAP-animatable property can respond to pre-extracted audio data.
+
+## Audio Data Format
+
+```js
+var AUDIO_DATA = {
+  fps: 30,
+  totalFrames: 900,
+  frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...]
+};
+```
+
+- `frames[i].bands[]` — frequency band amplitudes, 0-1. Index 0 = bass, higher = treble.
+- Each band normalized independently across the full track.
+
+## Mapping Audio to Visuals
+
+| Audio signal           | Visual property                   | Effect                     |
+| ---------------------- | --------------------------------- | -------------------------- |
+| Bass (bands[0])        | `scale`                           | Pulse on beat              |
+| Treble (bands[12-14])  | `textShadow`, `boxShadow`         | Glow intensity             |
+| Overall amplitude      | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |
+| Mid-range (bands[4-8]) | `borderRadius`, `width`           | Shape morphing             |
+
+Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties.
+
+## Content, Not Medium
+
+Audio provides **timing and intensity**. The visual vocabulary comes from the narrative.
+
+**Never add:** equalizer bars, spectrum analyzers, waveform displays, musical notes clip art, generic particle systems, rainbow color cycling, strobing white on beats, abstract pulsing orbs.
+
+**Instead:** Let content guide the visual and audio drive its behavior. Bass makes warmth _swell_. Treble sharpens _contrast_. The visual choice comes from "what does this piece feel like?"
+
+## Sampling Pattern
+
+Audio reactivity requires per-frame sampling via a `for` loop with `tl.call()`, not a single tween:
+
+```js
+// ✅ Correct — sample every frame
+for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    (function (frame) {
+      return function () {
+        draw(frame);
+      };
+    })(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+
+// ❌ Wrong — single tween, doesn't react to audio
+gsap.to(".el", { scale: 1.2, duration: totalDuration });
+```
+
+Without per-frame sampling, the composition doesn't actually react to audio.
+
+## textShadow Gotcha
+
+`textShadow` on a parent container with semi-transparent children (e.g., inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind all children. Fix: apply `scale` to the container for beat pulse, but apply `textShadow` to individual active words only.
+
+## Guidelines
+
+- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.
+- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.
+- **Match the energy** — corporate = subtle; music video = dramatic.
+- **Deterministic** — pre-extracted data, no Web Audio API, no runtime analysis.
+
+## Constraints
+
+- All audio data must be pre-extracted (use `extract-audio-data.py` from the gsap skill's scripts/)
+- No `Math.random()` or `Date.now()`
+- Audio reactivity runs on the same GSAP timeline as everything else
@@ -0,0 +1,132 @@
+# Captions
+
+## Language Rule (Non-Negotiable)
+
+**Never use `.en` models unless the user explicitly states the audio is English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.
+
+1. User says the language → `--model small --language <code>` (no `.en`)
+2. User says English → `--model small.en`
+3. Language unknown → `--model small` (no `.en`, no `--language`) — auto-detects
+
+---
+
+Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.
+
+## Transcript Source
+
+```json
+[
+  { "text": "Hello", "start": 0.0, "end": 0.5 },
+  { "text": "world.", "start": 0.6, "end": 1.2 }
+]
+```
+
+For transcription commands, whisper models, external APIs, see [transcript-guide.md](transcript-guide.md).
+
+## Style Detection (When No Style Specified)
+
+Read the full transcript before choosing. Four dimensions:
+
+**1. Visual feel** — corporate→clean; energetic→bold; storytelling→elegant; technical→precise; social→playful.
+
+**2. Color palette** — dark+bright for energy; muted for professional; high contrast for clarity; one accent color.
+
+**3. Font mood** — heavy/condensed for impact; clean sans for modern; rounded for friendly; serif for elegance.
+
+**4. Animation character** — scale-pop for punchy; gentle fade for calm; word-by-word for emphasis; typewriter for technical.
+
+## Per-Word Styling
+
+Scan for words deserving distinct treatment:
+
+- **Brand/product names** — larger size, unique color
+- **ALL CAPS** — scale boost, flash, accent color
+- **Numbers/statistics** — bold weight, accent color
+- **Emotional keywords** — exaggerated animation (overshoot, bounce)
+- **Call-to-action** — highlight, underline, color pop
+- **Marker highlight** — for beyond-color emphasis, see [css-patterns.md](css-patterns.md)
+
+## Script-to-Style Mapping
+
+| Tone         | Font mood                | Animation                          | Color                       | Size    |
+| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
+| Hype/launch  | Heavy condensed, 800-900 | Scale-pop, back.out(1.7), 0.1-0.2s | Bright on dark              | 72-96px |
+| Corporate    | Clean sans, 600-700      | Fade+slide, power3.out, 0.3s       | White/neutral, muted accent | 56-72px |
+| Tutorial     | Mono/clean sans, 500-600 | Typewriter/fade, 0.4-0.5s          | High contrast, minimal      | 48-64px |
+| Storytelling | Serif/elegant, 400-500   | Slow fade, power2.out, 0.5-0.6s    | Warm muted tones            | 44-56px |
+| Social       | Rounded sans, 700-800    | Bounce, elastic.out, word-by-word  | Playful, colored pills      | 56-80px |
+
+## Word Grouping
+
+- **High energy:** 2-3 words. Quick turnover.
+- **Conversational:** 3-5 words. Natural phrases.
+- **Measured/calm:** 4-6 words. Longer groups.
+
+Break on sentence boundaries, 150ms+ pauses, or max word count.
+
+## Positioning
+
+- **Landscape (1920x1080):** Bottom 80-120px, centered
+- **Portrait (1080x1920):** Lower middle ~600-700px from bottom, centered
+- Never cover the subject's face
+- `position: absolute` — never relative
+- One caption group visible at a time
+
+## Text Overflow Prevention
+
+Use `window.__hyperframes.fitTextFontSize()`:
+
+```js
+var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
+  fontFamily: "Outfit",
+  fontWeight: 900,
+  maxWidth: 1600,
+});
+el.style.fontSize = result.fontSize + "px";
+```
+
+Options: `maxWidth` (1600 landscape, 900 portrait), `baseFontSize` (78), `minFontSize` (42), `fontWeight`, `fontFamily`, `step` (2).
+
+CSS safety nets: `max-width` on container, `overflow: visible` (**not** `hidden` — hidden clips scaled emphasis words and glow effects), `position: absolute`, explicit `height`. When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom.
+
+**Container pattern:** Full-width absolute container, centered. Do **not** use `left: 50%; transform: translateX(-50%)` — causes clipping at composition edges.
+
+## Caption Exit Guarantee
+
+Every group **must** have a hard kill after exit animation:
+
+```js
+tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
+tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill
+```
+
+Self-lint after building timeline — place **before** `window.__timelines[id] = tl` so it runs at composition init:
+
+```js
+GROUPS.forEach(function (group, gi) {
+  var el = document.getElementById("cg-" + gi);
+  if (!el) return;
+  tl.seek(group.end + 0.01);
+  var computed = window.getComputedStyle(el);
+  if (computed.opacity !== "0" && computed.visibility !== "hidden") {
+    console.warn(
+      "[caption-lint] group " + gi + " still visible at t=" + (group.end + 0.01).toFixed(2) + "s",
+    );
+  }
+});
+tl.seek(0);
+```
+
+## Further References
+
+- [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation
+- [transcript-guide.md](transcript-guide.md) — transcription commands, whisper models, external APIs
+- [css-patterns.md](css-patterns.md) — CSS+GSAP marker highlighting (deterministic, fully seekable)
+
+## Constraints
+
+- Deterministic. No `Math.random()`, no `Date.now()`.
+- Sync to transcript timestamps.
+- One group visible at a time.
+- Every group must have a hard `tl.set` kill at `group.end`.
+- The compiler embeds supported fonts automatically — just declare `font-family` in CSS.
@@ -0,0 +1,373 @@
+# CSS Patterns for Marker Highlighting
+
+Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.
+
+## Table of Contents
+
+- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text
+- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text
+- [3. Burst Mode](#3-burst-mode) — Radiating lines from text
+- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text
+- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline
+
+## 1. Highlight Mode
+
+Yellow marker sweep behind text. The most common mode.
+
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+
+```css
+.mh-highlight-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-highlight-bar {
+  position: absolute;
+  top: 0;
+  left: -6px;
+  right: -6px;
+  bottom: 0;
+  background: #fdd835;
+  opacity: 0.35;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: 3px;
+  z-index: 0;
+}
+.mh-highlight-text {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+// Sweep in from left
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+
+// Optional: skew for hand-drawn feel
+// gsap.set("#hl-1", { skewX: -2 });
+```
+
+### Multi-line Highlight
+
+Stagger bars across multiple lines:
+
+```js
+tl.to(
+  ".mh-highlight-bar",
+  {
+    scaleX: 1,
+    duration: 0.5,
+    ease: "power2.out",
+    stagger: 0.3,
+  },
+  0.6,
+);
+```
+
+## 2. Circle Mode
+
+Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
+
+```html
+<span class="mh-circle-wrap">
+  <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
+  <span class="mh-circle-ring" id="circle-1"></span>
+</span>
+```
+
+```css
+.mh-circle-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-circle-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-circle-ring {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 130%;
+  height: 160%;
+  transform: translate(-50%, -50%) rotate(-3deg) scale(0);
+  border: 3px solid #e53935;
+  border-radius: 50%;
+  pointer-events: none;
+  z-index: 0;
+}
+```
+
+```js
+// Circle scales in with a wobble
+tl.to(
+  "#circle-1",
+  {
+    scale: 1,
+    rotation: -3,
+    duration: 0.6,
+    ease: "back.out(1.7)",
+    transformOrigin: "center center",
+  },
+  0.7,
+);
+```
+
+### Variations
+
+```css
+/* Tighter circle (for short words) */
+.mh-circle-ring.tight {
+  width: 150%;
+  height: 180%;
+}
+
+/* Squared circle (rounded rectangle) */
+.mh-circle-ring.rounded {
+  border-radius: 30%;
+  width: 120%;
+  height: 140%;
+}
+
+/* Ellipse (wider than tall) */
+.mh-circle-ring.ellipse {
+  width: 150%;
+  height: 130%;
+  border-radius: 50%;
+}
+```
+
+## 3. Burst Mode
+
+Radiating lines from text center. Each line is a positioned div rotated to its angle.
+
+```html
+<span class="mh-burst-wrap">
+  <span class="mh-burst-text">WOW</span>
+  <span class="mh-burst-container" id="burst-1">
+    <span class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></span>
+    <span class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></span>
+    <span class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></span>
+    <span class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></span>
+    <span class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></span>
+    <span class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></span>
+    <span class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></span>
+    <span class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-burst-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-burst-text {
+  position: relative;
+  z-index: 2;
+}
+.mh-burst-container {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  z-index: 1;
+}
+.mh-burst-line {
+  position: absolute;
+  display: block;
+  width: 3px;
+  height: var(--len);
+  background: #1e88e5;
+  left: -1.5px;
+  top: calc(-1 * var(--len));
+  transform: rotate(var(--angle));
+  transform-origin: bottom center;
+  opacity: 0;
+}
+```
+
+```js
+// All lines burst outward simultaneously with slight stagger
+tl.fromTo(
+  "#burst-1 .mh-burst-line",
+  { scaleY: 0, opacity: 0 },
+  { scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },
+  0.7,
+);
+```
+
+**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.
+
+## 4. Scribble Mode
+
+Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
+
+```html
+<span class="mh-scribble-wrap">
+  <span class="mh-scribble-text">underlined text</span>
+  <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
+    <path
+      id="scribble-1"
+      d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"
+      fill="none"
+      stroke="#FDD835"
+      stroke-width="3"
+      stroke-linecap="round"
+    />
+  </svg>
+</div>
+```
+
+```css
+.mh-scribble-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-scribble-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-scribble-svg {
+  position: absolute;
+  left: 0;
+  bottom: -6px;
+  width: 100%;
+  height: 24px;
+  z-index: 0;
+}
+```
+
+```js
+// Measure path length and set initial dash state
+var path = document.querySelector("#scribble-1");
+var len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+
+// Draw the line
+tl.to(
+  "#scribble-1",
+  {
+    strokeDashoffset: 0,
+    duration: 0.8,
+    ease: "power1.inOut",
+  },
+  0.7,
+);
+```
+
+### Strikethrough Variant
+
+Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.
+
+### Wavy Path Generator
+
+Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:
+
+- **Tight waves**: smaller x-increments (25px per half-wave)
+- **Loose waves**: larger x-increments (50px per half-wave)
+- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)
+
+## 5. Sketchout Mode
+
+Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
+
+```html
+<span class="mh-sketchout-wrap">
+  <span class="mh-sketchout-text">old price</span>
+  <span class="mh-sketchout-lines" id="sketchout-1">
+    <span class="mh-sketchout-line mh-sketchout-fwd"></span>
+    <span class="mh-sketchout-line mh-sketchout-bwd"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-sketchout-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-sketchout-text {
+  position: relative;
+  z-index: 0;
+}
+.mh-sketchout-lines {
+  position: absolute;
+  top: 0;
+  left: -4px;
+  right: -4px;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 1;
+}
+.mh-sketchout-line {
+  position: absolute;
+  display: block;
+  top: 50%;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  background: #e53935;
+  transform-origin: left center;
+  transform: scaleX(0);
+}
+.mh-sketchout-fwd {
+  transform: scaleX(0) rotate(-12deg);
+}
+.mh-sketchout-bwd {
+  transform: scaleX(0) rotate(12deg);
+}
+```
+
+```js
+// Forward slash draws first
+tl.to(
+  "#sketchout-1 .mh-sketchout-fwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.0,
+);
+
+// Backward slash follows
+tl.to(
+  "#sketchout-1 .mh-sketchout-bwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.15,
+);
+```
+
+## Combining Modes in Captions
+
+Use mode cycling for visual variety across caption groups:
+
+```js
+var MODES = ["highlight", "circle", "burst", "scribble"];
+
+GROUPS.forEach(function (group, gi) {
+  var mode = MODES[gi % MODES.length];
+  // Apply the mode's CSS pattern to emphasis words in this group
+  group.emphasisWords.forEach(function (word) {
+    applyMode(word.el, mode, tl, word.start);
+  });
+});
+```
+
+Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.
@@ -0,0 +1,90 @@
+# Dynamic Caption Techniques
+
+You are here because SKILL.md told you to read this file before writing animation code. Pick your technique combination from the table below based on the energy level you detected from the transcript, then implement using standard GSAP patterns.
+
+## Technique Selection by Energy
+
+| Energy level | Highlight                             | Exit                | Cycle pattern                             |
+| ------------ | ------------------------------------- | ------------------- | ----------------------------------------- |
+| High         | Karaoke with accent glow + scale pop  | Scatter or drop     | Alternate highlight styles every 2 groups |
+| Medium-high  | Karaoke with color pop                | Scatter or collapse | Alternate every 3 groups                  |
+| Medium       | Karaoke (subtle, white only)          | Fade + slide        | Alternate every 3 groups                  |
+| Medium-low   | Karaoke (minimal scale change)        | Fade                | Single style, vary ease per group         |
+| Low          | Karaoke (warm tones, slow transition) | Collapse            | Alternate every 4 groups                  |
+
+**All energy levels use karaoke highlight as the baseline.** The difference is intensity — high energy gets accent color + glow + 15% scale pop on active words, low energy gets a gentle white shift with 3% scale.
+
+**Emphasis words always break the pattern.** When a word is flagged as emphasis (emotional keyword, ALL CAPS, brand name), give it a stronger animation than surrounding words (larger scale, accent color, overshoot ease). This creates contrast.
+
+**Marker highlight modes add a visual layer on top of karaoke.** For emphasis words that need more than color/scale, add a marker-style effect — highlight sweep, circle, burst, or scribble — using the `/marker-highlight` skill. Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.
+
+## Audio-Reactive Captions (Mandatory for Music)
+
+**If the source audio is music (vocals over instrumentation, beats, any musical content), you MUST extract audio data and add audio-reactive animations.** This is not optional — music without audio reactivity looks disconnected. Even low-energy ballads get subtle bass pulse and treble glow.
+
+No special wiring is needed. The group loop already iterates over every caption group to build entrance, karaoke, and exit tweens. At that point, read the audio data for each group's time range and use it to modulate the group's animation intensity with regular GSAP tweens.
+
+```js
+// Load audio data inline (same pattern as TRANSCRIPT)
+var AUDIO = JSON.parse(audioDataJson); // { fps, totalFrames, frames: [{ bands: [...] }] }
+
+GROUPS.forEach(function (group, gi) {
+  var groupEl = document.getElementById("cg-" + gi);
+  if (!groupEl) return;
+
+  // Read peak energy for this group's time range
+  var startFrame = Math.floor(group.start * AUDIO.fps);
+  var endFrame = Math.min(Math.floor(group.end * AUDIO.fps), AUDIO.totalFrames - 1);
+  var peakBass = 0;
+  var peakTreble = 0;
+  for (var f = startFrame; f <= endFrame; f++) {
+    var frame = AUDIO.frames[f];
+    if (!frame) continue;
+    peakBass = Math.max(peakBass, frame.bands[0] || 0, frame.bands[1] || 0);
+    peakTreble = Math.max(peakTreble, frame.bands[6] || 0, frame.bands[7] || 0);
+  }
+
+  // Modulate entrance — louder groups enter bigger and glowier
+  tl.to(
+    groupEl,
+    {
+      scale: 1 + peakBass * 0.06,
+      textShadow:
+        "0 0 " + Math.round(peakTreble * 12) + "px rgba(255,255,255," + peakTreble * 0.4 + ")",
+      duration: 0.3,
+      ease: "power2.out",
+    },
+    group.start,
+  );
+
+  // Reset at exit so audio-driven values don't persist
+  tl.set(groupEl, { scale: 1, textShadow: "none" }, group.end - 0.15);
+});
+```
+
+This shapes the animation at build time, not playback time — no per-frame callbacks, no `tl.call()` loops, no async fetch timing issues. Loud groups come in with more weight and glow; quiet groups come in soft. The audio data modulates _how much_, the content determines _what_.
+
+Keep audio reactivity subtle — 3-6% scale variation and soft glow. Heavy pulsing makes text unreadable.
+
+To generate the audio data file:
+
+```bash
+python3 skills/gsap-effects/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json
+```
+
+## Combining Techniques
+
+Don't use the same highlight animation on every group — cycle through styles using the group index. Don't combine multiple competing animations on the same word at the same timestamp. Vary techniques across groups to match the content's pace changes.
+
+**Marker highlight effects** (from the `/marker-highlight` skill) layer well with karaoke — use karaoke for the word-by-word reveal, then add a marker effect on emphasis words only. For example: karaoke highlights each word in white, but brand names get a yellow highlight sweep and stats get a red circle. Cycle marker modes across groups for visual variety (see the mode-to-energy mapping in the marker-highlight skill).
+
+## Available Tools
+
+These tools are available in the HyperFrames runtime. Use them when they solve a real problem — not every composition needs all of them.
+
+| Tool                | What it does                                                              | Access                                                                                         | When it's useful                                                             |
+| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **pretext**         | Pure-arithmetic text measurement without DOM reflow. 0.0002ms per call.   | `window.__hyperframes.pretext.prepare(text, font)` / `.layout(prepared, maxWidth, lineHeight)` | Per-frame text reflow, shrinkwrap containers, computing layout before render |
+| **fitTextFontSize** | Finds the largest font size that fits text on one line. Built on pretext. | `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`             | Overflow prevention for long phrases, portrait mode, large base sizes        |
+| **audio data**      | Pre-extracted per-frame RMS energy and frequency bands.                   | Extract with `extract-audio-data.py`, load inline or via `fetch("audio-data.json")`            | Audio-reactive visuals — modulate intensity based on the music               |
+| **GSAP**            | Animation timeline with tweens and callbacks.                             | `gsap.to()`, `gsap.set()`, `tl.to()`, `tl.set()`                                               | All caption animation                                                        |
@@ -0,0 +1,69 @@
+# Motion Principles
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights — no more than 2 independent tweens with the same ease in a scene.
+- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3× slower than the fastest. Vary duration deliberately.
+- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.
+- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.
+- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.
+- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.
+
+## What You Don't Do Without Being Told
+
+### Easing is emotion, not technique
+
+The transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.
+
+**Direction rules — these are not optional:**
+
+- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.
+- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.
+- `.inOut` for elements moving between positions.
+
+You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
+
+### Speed communicates weight
+
+- Fast (0.15-0.3s) — energy, urgency, confidence
+- Medium (0.3-0.5s) — professional, most content
+- Slow (0.5-0.8s) — gravity, luxury, contemplation
+- Very slow (0.8-2.0s) — cinematic, emotional, atmospheric
+
+### Scene structure: build / breathe / resolve
+
+Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
+
+- **Build (0-30%)** — elements enter, staggered. Don't dump everything at once.
+- **Breathe (30-70%)** — content visible, alive with ONE ambient motion.
+- **Resolve (70-100%)** — exit or decisive end. Exits are faster than entrances.
+
+### Transitions are meaning
+
+- **Crossfade** = "this continues"
+- **Hard cut** = "wake up" / disruption
+- **Slow dissolve** = "drift with me"
+
+You crossfade everything. Use hard cuts for disruption and register shifts.
+
+### Choreography is hierarchy
+
+The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion — overlap entries. Total stagger sequence under 500ms regardless of item count.
+
+### Asymmetry
+
+Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
+
+## Visual Composition
+
+You build for the web. Video frames are not pages.
+
+- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.
+- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.
+- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).
+- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as "nothing loaded."
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
+- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
+- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
@@ -0,0 +1,151 @@
+# Transcript Guide
+
+## How Transcripts Are Generated
+
+`hyperframes transcribe` handles both transcription and format conversion:
+
+```bash
+# Transcribe audio/video (uses whisper.cpp locally, no API key needed)
+npx hyperframes transcribe audio.mp3
+
+# Use a larger model for better accuracy
+npx hyperframes transcribe audio.mp3 --model medium.en
+
+# Filter to English only (skips non-English speech)
+npx hyperframes transcribe audio.mp3 --language en
+
+# Import an existing transcript from another tool
+npx hyperframes transcribe captions.srt
+npx hyperframes transcribe captions.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+## Supported Input Formats
+
+The CLI auto-detects and normalizes these formats:
+
+| Format                | Extension | Source                                                                      | Word-level?       |
+| --------------------- | --------- | --------------------------------------------------------------------------- | ----------------- |
+| whisper.cpp JSON      | `.json`   | `hyperframes init --video`, `hyperframes transcribe`                        | Yes               |
+| OpenAI Whisper API    | `.json`   | `openai.audio.transcriptions.create({ timestamp_granularities: ["word"] })` | Yes               |
+| SRT subtitles         | `.srt`    | Video editors, subtitle tools, YouTube                                      | No (phrase-level) |
+| VTT subtitles         | `.vtt`    | Web players, YouTube, transcription services                                | No (phrase-level) |
+| Normalized word array | `.json`   | Pre-processed by any tool                                                   | Yes               |
+
+**Word-level timestamps produce better captions.** SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.
+
+## Whisper Model Guide
+
+The default model (`small.en`) balances accuracy and speed. For better results, use a larger model:
+
+| Model      | Size   | Speed    | Accuracy  | When to use                           |
+| ---------- | ------ | -------- | --------- | ------------------------------------- |
+| `tiny`     | 75 MB  | Fastest  | Low       | Quick previews, testing pipeline      |
+| `base`     | 142 MB | Fast     | Fair      | Short clips, clear audio              |
+| `small`    | 466 MB | Moderate | Good      | **Default** — good for most content   |
+| `medium`   | 1.5 GB | Slow     | Very good | Important content, noisy audio, music |
+| `large-v3` | 3.1 GB | Slowest  | Best      | Production quality                    |
+
+**Only add `.en` suffix when the user explicitly says the audio is English.** `.en` models are slightly more accurate for English but will TRANSLATE non-English audio instead of transcribing it.
+
+**Critical: `.en` models translate non-English audio into English** — they don't transcribe it. If the audio might not be English, always use a model without the `.en` suffix and pass `--language` to specify the source language. If you're unsure of the language, use `small` (not `small.en`) without `--language` — whisper will auto-detect.
+
+```bash
+# Spanish audio
+npx hyperframes transcribe audio.mp3 --model small --language es
+
+# Unknown language — let whisper auto-detect
+npx hyperframes transcribe audio.mp3 --model small
+```
+
+**Music and vocals over instrumentation**: `small.en` will misidentify lyrics — use `medium.en` as the minimum, or import lyrics manually. Even `medium.en` struggles with heavily produced tracks; for music videos, providing known lyrics as an SRT/VTT and importing with `hyperframes transcribe lyrics.srt` will always beat automated transcription.
+
+## Transcript Quality Check (Mandatory)
+
+After every transcription, **read the transcript and check for quality issues before proceeding.** Bad transcripts produce nonsensical captions. Never skip this step.
+
+### What to look for
+
+| Signal                       | Example                                | Cause                                                                        |
+| ---------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| Music note tokens (`♪`, `�`) | `{ "text": "♪" }` or `{ "text": "�" }` | Whisper detected music, not speech                                           |
+| Garbled / nonsense words     | "Do a chin", "Get so gay", "huh"       | Model misheard lyrics or background noise                                    |
+| Long gaps with no words      | 20+ seconds of only `♪` tokens         | Instrumental section — expected, but high ratio means speech is being missed |
+| Repeated filler              | Many "huh", "uh", "oh" entries         | Model is hallucinating on music                                              |
+| Very short word spans        | Words with `end - start < 0.05`        | Unreliable timestamp alignment                                               |
+
+### Automatic retry rules
+
+**If more than 20% of entries are `♪`/`�` tokens, or the transcript contains obvious nonsense words, the transcription failed.** Do not proceed with the bad transcript. Instead:
+
+1. **Retry with `medium.en`** if the original used `small.en` or smaller:
+   ```bash
+   npx hyperframes transcribe audio.mp3 --model medium.en
+   ```
+2. **If `medium.en` also fails** (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:
+   - Providing lyrics manually as an SRT/VTT file
+   - Using an external API (OpenAI or Groq Whisper — see below)
+3. **Always clean the transcript** before building captions — filter out `♪`/`�` tokens and entries where `text` is a single non-word character. Only real words should reach the caption composition.
+
+### Cleaning a transcript
+
+After transcription (even with a good model), strip non-word entries:
+
+```js
+var raw = JSON.parse(transcriptJson);
+var words = raw.filter(function (w) {
+  if (!w.text || w.text.trim().length === 0) return false;
+  if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;
+  if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;
+  return true;
+});
+```
+
+### When to use which model (decision tree)
+
+1. **Is this speech over silence/light background?** → `small.en` is fine
+2. **Is this speech over music, or music with vocals?** → Start with `medium.en`
+3. **Is this a produced music track (vocals + full instrumentation)?** → Start with `medium.en`, expect to need manual lyrics or an external API
+4. **Is this multilingual?** → Use `medium` or `large-v3` (no `.en` suffix)
+
+## Using External Transcription APIs
+
+For the best accuracy, use an external API and import the result:
+
+**OpenAI Whisper API** (recommended for quality):
+
+```bash
+# Generate with word timestamps, then import
+curl https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-1 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-openai.json
+
+npx hyperframes transcribe transcript-openai.json
+```
+
+**Groq Whisper API** (fast, free tier available):
+
+```bash
+curl https://api.groq.com/openai/v1/audio/transcriptions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-large-v3 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-groq.json
+
+npx hyperframes transcribe transcript-groq.json
+```
+
+## If No Transcript Exists
+
+1. Check the project root for `transcript.json`, `.srt`, or `.vtt` files
+2. If none found, run transcription — pick the starting model based on the content type:
+   - Speech/voiceover → `small.en`
+   - Music with vocals → `medium.en`
+   ```bash
+   npx hyperframes transcribe <audio-or-video-file> --model medium.en
+   ```
+3. **Read the transcript and run the quality check** (see above). If it fails, retry with a larger model or suggest manual lyrics.
@@ -0,0 +1,112 @@
+# Scene Transitions
+
+A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+
+## Animation Rules for Multi-Scene Compositions
+
+These are non-negotiable for every multi-scene composition:
+
+1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
+2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.
+3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
+4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
+
+## Energy → Primary Transition
+
+| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
+| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
+| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
+| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
+| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
+
+Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
+
+## Mood → Transition Type
+
+Think about what the transition _communicates_, not just what it looks like.
+
+| Mood                     | Transitions                                                                                                                          | Why it works                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn · **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |
+| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens                                                   | Content transforms mechanically — compressed, shrunk, sliced, gridded.                      |
+| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |
+| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split                                  | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
+| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |
+| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |
+| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |
+| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black · **Shader:** cross-warp morph, thermal distortion                                    | Restraint. Cross-warp morph flows both scenes into each other organically.                  |
+| **Retro / analog**       | Film burn, light leak, VHS, clock wipe · **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |
+
+## Narrative Position
+
+| Position                   | Use                                                                        | Why                                                   |
+| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Opening**                | Your most distinctive transition. Match the mood. 0.4-0.6s                 | Sets the visual language for the entire piece.        |
+| **Between related points** | Your primary transition. Consistent. 0.3s                                  | Don't distract — the content is continuing.           |
+| **Topic change**           | Something different from your primary. Staggered blocks, shutter, squeeze. | Signals "new section" — the viewer's brain resets.    |
+| **Climax / hero reveal**   | Your boldest accent. Fastest or most dramatic.                             | This is the payoff — spend your best transition here. |
+| **Wind-down**              | Return to gentle. Blur crossfade, crossfade. 0.5-0.7s                      | Let the viewer exhale after the climax.               |
+| **Outro**                  | Slowest, simplest. Crossfade, color dip to black. 0.6-1.0s                 | Closure. Don't introduce new energy at the end.       |
+
+## Blur Intensity by Energy
+
+| Energy     | Blur    | Duration | Hold at peak |
+| ---------- | ------- | -------- | ------------ |
+| **Calm**   | 20-30px | 0.8-1.2s | 0.3-0.5s     |
+| **Medium** | 8-15px  | 0.4-0.6s | 0.1-0.2s     |
+| **High**   | 3-6px   | 0.2-0.3s | 0s           |
+
+## Presets
+
+| Preset     | Duration | Easing            |
+| ---------- | -------- | ----------------- |
+| `snappy`   | 0.2s     | `power4.inOut`    |
+| `smooth`   | 0.4s     | `power2.inOut`    |
+| `gentle`   | 0.6s     | `sine.inOut`      |
+| `dramatic` | 0.5s     | `power3.in` → out |
+| `instant`  | 0.15s    | `expo.inOut`      |
+| `luxe`     | 0.7s     | `power1.inOut`    |
+
+## Implementation
+
+Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
+
+| Category    | CSS                                                            | Shader (WebGL)                                                            |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |
+| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |
+| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |
+| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |
+| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | —                                                                         |
+| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |
+| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
+| Pattern     | Grid dissolve, morph circle                                    | —                                                                         |
+
+## Transitions That Don't Work in CSS
+
+Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
+
+## CSS vs Shader
+
+CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
+
+**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
+
+When a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.
+
+## Shader-Compatible CSS Rules
+
+Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
+
+1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
+2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
+3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
+4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
+5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
+6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.
+
+These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
+
+## Visual Pattern Warning
+
+Avoid transitions that create visible repeating geometric patterns — grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.
@@ -0,0 +1,117 @@
+# Transition Catalog
+
+Hard rules, scene template, and routing to implementation code. Read the reference file for the transition type you need — don't load all of them.
+
+## Hard Rules (CSS)
+
+These cause real bugs if violated.
+
+**Scene visibility:** Scene 1 visible by default (no `opacity: 0`). Scenes 2+ have `opacity: 0` on the CONTAINER div. GSAP reveals them. No visibility shim (`timedEls`).
+
+**Fonts:** Just write the `font-family` you want — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No need for `<link>` tags or `@import`. Works in all contexts including sandboxed iframes.
+
+**Element structure:** No `class="clip"` on scene divs in standalone compositions. Only the root div gets `data-composition-id`/`data-start`/`data-duration`.
+
+**Overlay elements:** Staggered blocks = full-screen 1920x1080, NOT thin strips. Glitch RGB overlays = normal blending at 35% opacity, NOT `mix-blend-mode: multiply` (invisible on dark backgrounds). Light leak overlays = larger than the frame (2400px+), never a visible shape. Overexposure = use `filter: brightness()` on the scene, not just a white overlay.
+
+**VHS tape:** Clone actual scene content with `cloneNode(true)`, NOT colored bars. Each strip: wider than frame (2020px at left:-50px). Red+blue chromatic copies at z-index above main strip. Seeded PRNG for deterministic random offsets.
+
+**Z-index:** Gravity drop, zoom out, diagonal split need outgoing scene ON TOP (`zIndex: 10`) so it exits while revealing the new scene behind (`zIndex: 1`).
+
+**Page burn:** Content burns with the page — no falling debris. Hide scene1 via `tl.set` at burn end, NEVER `onComplete` (not reversible). `onUpdate` must restore `clipPath: "none"` when `wp <= 0` for rewind support. Incoming scene fades from black at 90% through burn.
+
+**Clock wipe:** 9-point polygon with intermediate edge positions. Step through 4 quadrants with separate tweens.
+
+**Grid dissolve:** Cycle 5 palette colors per cell, not monochrome.
+
+**Blinds count by energy:** Calm: 4h/6v. Medium: 6-8h/8v. High: 12-16h/16v.
+
+**Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).
+
+## Shader Transitions
+
+Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".
+
+## Scene Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #000;
+        font-family: "YOUR FONT", sans-serif; /* compiler embeds supported fonts automatically */
+      }
+      .scene {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      #scene1 {
+        z-index: 1;
+        background: #color;
+      }
+      #scene2 {
+        z-index: 2;
+        background: #color;
+        opacity: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="TOTAL"
+    >
+      <div id="scene1" class="scene"><!-- visible --></div>
+      <div id="scene2" class="scene"><!-- hidden --></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      // Transition code here
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Every transition follows: position new scene → animate outgoing → swap → animate incoming → clean up overlays.
+
+## CSS Transitions
+
+All code examples use `old` for the outgoing scene-inner selector and `new` for the incoming, with `T` as the transition start time. Read the reference file for the type you need.
+
+| Type           | Transitions                                          | Reference                                  |
+| -------------- | ---------------------------------------------------- | ------------------------------------------ |
+| Push           | Push slide, vertical push, elastic push, squeeze     | [css-push.md](./css-push.md)               |
+| Radial / Shape | Circle iris, diamond iris, diagonal split            | [css-radial.md](./css-radial.md)           |
+| 3D             | 3D card flip                                         | [css-3d.md](./css-3d.md)                   |
+| Scale / Zoom   | Zoom through, zoom out                               | [css-scale.md](./css-scale.md)             |
+| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | [css-dissolve.md](./css-dissolve.md)       |
+| Cover          | Staggered blocks, horizontal blinds, vertical blinds | [css-cover.md](./css-cover.md)             |
+| Light          | Light leak, overexposure burn, film burn             | [css-light.md](./css-light.md)             |
+| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | [css-distortion.md](./css-distortion.md)   |
+| Mechanical     | Shutter, clock wipe                                  | [css-mechanical.md](./css-mechanical.md)   |
+| Grid           | Grid dissolve                                        | [css-grid.md](./css-grid.md)               |
+| Other          | Gravity drop, morph circle                           | [css-other.md](./css-other.md)             |
+| Blur           | Blur through, directional blur                       | [css-blur.md](./css-blur.md)               |
+| Destruction    | Page burn                                            | [css-destruction.md](./css-destruction.md) |
+
+## Shader Transitions
+
+WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.
@@ -0,0 +1,12 @@
+## 3D
+
+### 3D Card Flip
+
+180° Y-axis rotation. Requires CSS: `backface-visibility: hidden; transform-style: preserve-3d;` on both scene-inners. Parent needs `perspective: 1200px`.
+
+```js
+tl.set(new, { rotationY: -180, opacity: 1 }, T);
+tl.to(old, { rotationY: 180, duration: 0.6, ease: "power2.inOut" }, T);
+tl.to(new, { rotationY: 0, duration: 0.6, ease: "power2.inOut" }, T);
+tl.set(old, { opacity: 0 }, T + 0.6);
+```
@@ -0,0 +1,51 @@
+## Blur
+
+All blur transitions scale with energy. See SKILL.md "Blur Intensity by Energy" for the full table.
+
+### Blur Through
+
+Content becomes fully abstract before resolving. The heaviest blur transition.
+
+**Calm (default for this type — it's inherently heavy):**
+
+```js
+tl.to(old, { filter: "blur(30px)", scale: 1.08, duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power1.in" }, T + 0.3);
+// Hold: both scenes in abstract blur state
+tl.fromTo(new,
+  { filter: "blur(30px)", scale: 0.92, opacity: 0 },
+  { filter: "blur(30px)", scale: 0.92, opacity: 1, duration: 0.2, ease: "none" }, T + 0.5);
+// Slow resolve
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.7, ease: "power1.out" }, T + 0.7);
+```
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", scale: 1.05, opacity: 0, duration: 0.4, ease: "power2.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(15px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.4, ease: "power2.out" }, T + 0.2);
+```
+
+### Directional Blur
+
+Blur + skew simulating motion in one direction. Scale blur and skew with energy.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(12px)", skewX: -8, x: -200, opacity: 0, duration: 0.4, ease: "power3.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(12px)", skewX: 8, x: 200, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.4, ease: "power3.out" }, T + 0.15);
+```
+
+**Calm (heavier blur, gentler motion):**
+
+```js
+tl.to(old, { filter: "blur(20px)", skewX: -4, x: -100, opacity: 0, duration: 0.6, ease: "power1.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(20px)", skewX: 4, x: 100, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.6, ease: "power1.out" }, T + 0.3);
+```
@@ -0,0 +1,43 @@
+## Cover
+
+### Staggered Color Blocks
+
+Full-screen (1920x1080) colored divs slide across staggered. Scene swaps while covered.
+
+**2-block** (standard):
+
+```js
+tl.set("#wipe-a", { x: -1920 }, T - 0.01);
+tl.set("#wipe-b", { x: -1920 }, T - 0.01);
+tl.to("#wipe-a", { x: 0, duration: 0.25, ease: "power3.inOut" }, T);
+tl.to("#wipe-b", { x: 0, duration: 0.25, ease: "power3.inOut" }, T + 0.06);
+tl.set(old, { opacity: 0 }, T + 0.2);
+tl.set(new, { opacity: 1 }, T + 0.2);
+tl.to("#wipe-a", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.28);
+tl.to("#wipe-b", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.34);
+```
+
+**5-block** (dense variant): same pattern with 5 blocks at 0.04s stagger. Use composition palette colors.
+
+### Horizontal Blinds
+
+Full-width strips slide across staggered. Each strip: `width: 1920px; height: Xpx`.
+
+**6 strips** (180px each): `0.03s` stagger
+**12 strips** (90px each): `0.018s` stagger
+
+```js
+for (var i = 0; i < N; i++) {
+  tl.set("#blind-h-" + i, { x: -1920 }, T - 0.01);
+  tl.fromTo("#blind-h-" + i, { x: -1920 }, { x: 0, duration: 0.2, ease: "power3.inOut" }, T + i * stagger);
+}
+tl.set(old, { opacity: 0 }, T + coverTime);
+tl.set(new, { opacity: 1 }, T + coverTime);
+for (var i = 0; i < N; i++) {
+  tl.to("#blind-h-" + i, { x: 1920, duration: 0.2, ease: "power3.inOut" }, T + exitStart + i * stagger);
+}
+```
+
+### Vertical Blinds
+
+Same as horizontal but strips are tall and narrow, moving on Y axis.
@@ -0,0 +1,95 @@
+## Destruction
+
+### Page Burn
+
+The outgoing scene literally burns away from a corner. A fire front expands with noise-based irregular edges, a canvas draws the scorched char line at the burn boundary, and individual text characters/elements chip off and fall with gravity as the fire reaches them. The incoming scene reveals behind the burn.
+
+This transition has three systems working together:
+
+1. **Fire geometry** — a radial front expanding from a corner (e.g., bottom-right) with noise-based irregularity for organic edges
+2. **Scene clipping** — the outgoing scene uses an SVG clip-path (with `fill-rule: evenodd`) that cuts a hole matching the fire front. As the fire expands, more of the scene is clipped away. All content (text, images, lines) burns with the page — no separate debris.
+3. **Scorched edge** — a `<canvas>` overlay draws a radial gradient fringe at the fire boundary to simulate charring
+
+**When to use:** Dramatic reveals, edgy/destructive mood, gaming, cyberpunk. This is the most dramatic transition in the catalog — reserve it for hero moments.
+
+**Requirements:**
+
+- A `<canvas>` element for the burn edge overlay
+- A noise function for organic fire edge geometry
+- SVG clip-path with evenodd fill-rule for the inverted clip
+
+**Fire geometry (deterministic noise):**
+
+```js
+function noise(x) {
+  var ix = Math.floor(x),
+    fx = x - ix;
+  var a = Math.sin(ix * 127.1 + 311.7) * 43758.5453;
+  var b = Math.sin((ix + 1) * 127.1 + 311.7) * 43758.5453;
+  var t = fx * fx * (3 - 2 * fx);
+  return a - Math.floor(a) + (b - Math.floor(b) - (a - Math.floor(a))) * t;
+}
+
+function fireRadiusAtAngle(angle, progress) {
+  var base = progress * maxRadius;
+  return (
+    base +
+    noise(angle * 3 + progress * 4) * 50 +
+    noise(angle * 8 + progress * 9) * 20 +
+    noise(angle * 15 + progress * 15) * 8
+  );
+}
+```
+
+**Incoming scene timing:** The incoming scene should NOT be visible during the burn. As the fire consumes the outgoing scene, **black shows through the holes** — this is the dramatic part. The viewer watches content being destroyed against blackness.
+
+At ~90% through the burn, the incoming scene fades in SLOWLY from black — the background first, then content staggered. Use long, gentle fades (`power1.out`, 0.8-1.2s durations) so it feels like the new scene materializes from darkness, not a hard swap.
+
+```js
+// Scene 2 stays at opacity: 0 during the burn — black behind the fire
+tl.set("#s2-title", { opacity: 0 }, T);
+tl.set("#s2-subtitle", { opacity: 0 }, T);
+
+// At 90% through, scene bg fades in slowly from black
+var contentReveal = T + BURN_DURATION * 0.9;
+tl.to("#scene2", { opacity: 1, duration: 1.2, ease: "power1.out" }, contentReveal);
+
+// Content fades in staggered on top, even slower
+tl.to("#s2-title", { opacity: 1, duration: 1.0, ease: "power1.out" }, contentReveal + 0.5);
+tl.to("#s2-subtitle", { opacity: 1, duration: 0.8, ease: "power1.out" }, contentReveal + 0.7);
+```
+
+**Content burns with the page — no falling debris.** The clip-path on scene1 IS the effect — as the fire shape expands, everything behind the fire edge (text, images, lines) disappears naturally. Don't clone elements, don't create falling debris. The content is part of the page being consumed. The scorched canvas edge provides the visual char line at the burn boundary.
+
+**Hide scene1 via `tl.set` at burn end — NEVER in `onComplete`.** Using `onComplete` to hide scene1 is not reversible when scrubbing. Instead, use a `tl.set` at the exact burn end time:
+
+```js
+tl.to(
+  burnState,
+  {
+    progress: 1,
+    duration: BURN_DURATION,
+    ease: "none",
+    onUpdate: function () {
+      var wp = burnState.progress;
+      var scene1 = document.getElementById("scene1");
+      if (wp <= 0) {
+        scene1.style.clipPath = "none"; // fully visible when rewound
+      } else if (wp < 1) {
+        scene1.style.clipPath = buildClipPath(wp);
+      }
+      drawEdge(wp);
+    },
+    // NO onComplete — use tl.set instead
+  },
+  T,
+);
+
+// Hide scene1 at exact burn end — reversible via timeline
+tl.set("#scene1", { opacity: 0 }, T + BURN_DURATION);
+tl.set("#scene1", { clipPath: "none" }, T + BURN_DURATION);
+```
+
+The `onUpdate` handles clip-path and canvas edge per-frame. The `tl.set` handles the final hide — and GSAP automatically reverses it when scrubbing backward, restoring scene1 to `opacity: 1`.
+
+The `onUpdate` callback is the key — it runs every frame to advance the clip-path and canvas edge in sync with the timeline.
@@ -0,0 +1,66 @@
+## Dissolve
+
+### Crossfade
+
+Simple opacity swap. The baseline.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.inOut" }, T);
+```
+
+### Blur Crossfade
+
+Dissolve with blur + scale shift. **Scale blur amount by energy** — see SKILL.md "Blur Intensity by Energy" section. The examples below show the medium (default) version. For calm compositions, increase to 20-30px with a 0.3-0.5s hold at peak blur. For high-energy, decrease to 3-6px with no hold.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(10px)", scale: 1.03, opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new,
+  { filter: "blur(10px)", scale: 0.97, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.5, ease: "power2.inOut" }, T + 0.1);
+```
+
+**Calm (wellness, luxury) — heavy blur, holds at abstract color:**
+
+```js
+tl.to(old, { filter: "blur(25px)", scale: 1.05, duration: 0.6, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.4, ease: "power1.in" }, T + 0.4);
+tl.fromTo(new,
+  { filter: "blur(25px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(25px)", scale: 0.95, opacity: 1, duration: 0.3, ease: "power1.inOut" }, T + 0.5);
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.6, ease: "power1.out" }, T + 0.8);
+```
+
+### Focus Pull
+
+Outgoing slowly blurs while incoming fades in sharp. Depth-of-field feel. **Scale blur amount and hold duration by energy.**
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power2.in" }, T + 0.25);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, T + 0.25);
+```
+
+**Calm — slow rack focus with long hold at peak defocus:**
+
+```js
+tl.to(old, { filter: "blur(30px)", duration: 0.8, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power1.in" }, T + 0.6);
+tl.fromTo(new, { opacity: 0, filter: "blur(20px)" },
+  { opacity: 1, filter: "blur(20px)", duration: 0.3, ease: "power1.inOut" }, T + 0.7);
+tl.to(new, { filter: "blur(0px)", duration: 0.6, ease: "power1.out" }, T + 1.0);
+```
+
+### Color Dip
+
+Fade to solid color, hold, fade up new scene.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.2, ease: "power2.in" }, T);
+// Background color shows through
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.2, ease: "power2.out" }, T + 0.25);
+```
@@ -0,0 +1,45 @@
+## Distortion
+
+### Glitch
+
+RGB-tinted overlays (NOT multiply blend — use normal blending at 35% opacity) jitter with large offsets. Scene itself also jitters.
+
+```js
+tl.set("#glitch-r", { opacity: 1, x: 40, y: -8 }, T);
+tl.set("#glitch-g", { opacity: 1, x: -30, y: 12 }, T);
+tl.set("#glitch-b", { opacity: 1, x: 15, y: -20 }, T);
+tl.set(old, { x: -15 }, T);
+// 6 jitter frames at 0.03s intervals with big offsets (±30-60px)
+// ... swap and clear at T + 0.2
+```
+
+### Chromatic Aberration
+
+RGB overlays start aligned then spread apart (±80px), scene fades, converge on new scene.
+
+```js
+tl.set("#glitch-r", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-g", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-b", { opacity: 0.6, x: 0 }, T);
+tl.to("#glitch-r", { x: -80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-b", { x: 80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-g", { y: 30, duration: 0.3, ease: "power2.in" }, T);
+// Swap at T + 0.3, converge back at T + 0.3
+```
+
+### Ripple
+
+Rapid oscillation (±30px) + scale distortion (0.97-1.03) + increasing blur. Swap at peak distortion.
+
+```js
+tl.to(old, { x: 30, scale: 1.02, duration: 0.04, ease: "none" }, T);
+tl.to(old, { x: -25, scale: 0.98, filter: "blur(4px)", duration: 0.04, ease: "none" }, T + 0.04);
+// ... more oscillations with increasing blur
+// Swap at peak, incoming stabilizes with decreasing wobble
+```
+
+### VHS Tape
+
+Clone scene into 20 horizontal strips (each 54px, clip-path'd). Each strip shifts x independently with seeded pseudo-random offsets at per-bar random intervals. Add red+blue chromatic offset copies on each strip (z-index above main, 35% opacity). Make strips wider than frame (2020px at left:-50px) so edges never show.
+
+See SKILL.md for clone-based implementation pattern.
@@ -0,0 +1,10 @@
+## Grid
+
+### Grid Dissolve
+
+Grid of colored cells covers the frame in a ripple from center. Scene swaps at 50% coverage. Cells fade out in ripple.
+
+**12-cell** (4x3, each 480x270): standard
+**120-cell** (12x10, each 160x108): dense variant — lower opacity (0.75), tighter ripple
+
+Cells are created dynamically in JS, sorted by distance from center for ripple stagger.
@@ -0,0 +1,49 @@
+## Light
+
+### Light Leak
+
+Multiple warm-colored overlays wash across frame. Needs: a flat warm tint layer + 2-3 bright radial gradient divs, all larger than the frame so edges are never visible.
+
+```js
+// Warm tint washes over entire frame
+tl.to("#leak-warm", { opacity: 0.4, duration: 0.3, ease: "power1.in" }, T);
+// Bright leak elements drift in
+tl.to("#leak-1", { opacity: 0.9, x: 300, duration: 0.5, ease: "sine.inOut" }, T + 0.05);
+tl.to("#leak-2", { opacity: 0.8, x: 200, duration: 0.6, ease: "sine.inOut" }, T + 0.1);
+// Peak warmth then swap
+tl.to("#leak-warm", { opacity: 0.6, duration: 0.15, ease: "power2.in" }, T + 0.35);
+tl.set(old, { opacity: 0 }, T + 0.45);
+tl.set(new, { opacity: 1 }, T + 0.45);
+// Leak fades
+tl.to("#leak-warm", { opacity: 0, duration: 0.4, ease: "power2.out" }, T + 0.5);
+tl.to("#leak-1", { opacity: 0, x: 600, duration: 0.35, ease: "power1.out" }, T + 0.5);
+```
+
+### Overexposure Burn
+
+Scene progressively blows out to white using CSS `filter: brightness()`, then white overlay fades in. Swap at peak white. White recedes to reveal new scene.
+
+```js
+tl.to(old, { filter: "brightness(1.5)", scale: 1.03, duration: 0.2, ease: "power1.in" }, T);
+tl.to(old, { filter: "brightness(3)", scale: 1.06, duration: 0.2, ease: "power2.in" }, T + 0.2);
+tl.to("#flash-overlay", { opacity: 0.5, duration: 0.25, ease: "power1.in" }, T + 0.15);
+tl.to("#flash-overlay", { opacity: 1, duration: 0.15, ease: "power2.in" }, T + 0.4);
+tl.set(old, { opacity: 0, filter: "brightness(1)", scale: 1 }, T + 0.55);
+tl.set(new, { opacity: 1 }, T + 0.55);
+tl.to("#flash-overlay", { opacity: 0, duration: 0.35, ease: "power2.out" }, T + 0.55);
+```
+
+### Film Burn
+
+Staggered warm overlays (amber, orange, red) bleed from one edge. Each overlay is a large radial gradient div at high z-index.
+
+```js
+tl.to("#burn-a", { opacity: 1, x: -300, duration: 0.4, ease: "power1.in" }, T);
+tl.to("#burn-b", { opacity: 1, x: -500, duration: 0.5, ease: "power1.in" }, T + 0.05);
+tl.to("#burn-c", { opacity: 1, x: -200, duration: 0.45, ease: "power1.in" }, T + 0.1);
+tl.set(old, { opacity: 0 }, T + 0.35);
+tl.set(new, { opacity: 1 }, T + 0.35);
+tl.to("#burn-a", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.45);
+tl.to("#burn-b", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.5);
+tl.to("#burn-c", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.55);
+```
@@ -0,0 +1,30 @@
+## Mechanical
+
+### Shutter
+
+Two full-screen halves close from top and bottom, meet in the middle. Swap while closed. Open again.
+
+```js
+tl.to("#shutter-top", { y: 0, duration: 0.25, ease: "power3.in" }, T);
+tl.to("#shutter-bot", { y: 0, duration: 0.25, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0 }, T + 0.25);
+tl.set(new, { opacity: 1 }, T + 0.25);
+tl.to("#shutter-top", { y: -540, duration: 0.25, ease: "power3.out" }, T + 0.3);
+tl.to("#shutter-bot", { y: 540, duration: 0.25, ease: "power3.out" }, T + 0.3);
+```
+
+### Clock Wipe
+
+Radial polygon sweep stepping through quadrants. Use 9-point polygon with intermediate edge positions for smooth sweep.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 10 }, T);
+var d = 0.1; // duration per quadrant
+tl.set(new, { clipPath: "polygon(50% 50%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%)" }, T);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 50%, 100% 50%, 100% 50%, 100% 50%, 100% 50%)", duration: d, ease: "none" }, T);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 50% 100%, 50% 100%, 50% 100%)", duration: d, ease: "none" }, T + d);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 0% 100%, 0% 50%, 0% 50%)", duration: d, ease: "none" }, T + d*2);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 0% 100%, 0% 50%, 0% 0%)", duration: d, ease: "none" }, T + d*3);
+tl.set(new, { clipPath: "none", zIndex: "auto" }, T + d*4 + 0.02);
+tl.set(old, { opacity: 0, zIndex: "auto" }, T + d*4 + 0.02);
+```
@@ -0,0 +1,25 @@
+## Other
+
+### Gravity Drop
+
+Old scene falls down with slight rotation. New scene was behind it. Needs z-index.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10 }, T);
+tl.to(old, { y: 1200, rotation: 4, duration: 0.5, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0, zIndex: "auto" }, T + 0.5);
+tl.set(new, { zIndex: "auto" }, T + 0.5);
+```
+
+### Morph Circle
+
+A circle scales up from center to fill frame (becoming the new scene's background color). New scene content fades in on top.
+
+```js
+tl.set("#morph-circle", { background: newBgColor, opacity: 1, scale: 0 }, T);
+tl.to("#morph-circle", { scale: 30, duration: 0.5, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0 }, T + 0.4);
+tl.set(new, { opacity: 1 }, T + 0.4);
+tl.to("#morph-circle", { opacity: 0, duration: 0.15, ease: "power2.out" }, T + 0.5);
+```
@@ -0,0 +1,41 @@
+## Linear / Push
+
+### Push Slide
+
+Both scenes move together — new pushes old out.
+
+```js
+tl.to(old, { x: -1920, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 0, duration: 0.5, ease: "power3.inOut" }, T);
+```
+
+### Vertical Push
+
+Same as push slide but vertical.
+
+```js
+tl.to(old, { y: -1080, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { y: 1080, opacity: 1 }, { y: 0, duration: 0.5, ease: "power3.inOut" }, T);
+```
+
+### Elastic Push
+
+Push with overshoot bounce on the incoming scene.
+
+```js
+tl.to(old, { x: -1920, duration: 0.5, ease: "power3.in" }, T);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 30, duration: 0.4, ease: "power4.out" }, T + 0.1);
+tl.to(new, { x: -15, duration: 0.15, ease: "sine.inOut" }, T + 0.5);
+tl.to(new, { x: 0, duration: 0.1, ease: "sine.out" }, T + 0.65);
+```
+
+### Squeeze
+
+Old compresses, new expands from opposite side.
+
+```js
+tl.to(old, { scaleX: 0, transformOrigin: "left center", duration: 0.4, ease: "power3.inOut" }, T);
+tl.fromTo(new, { scaleX: 0, transformOrigin: "right center", opacity: 1 },
+  { scaleX: 1, duration: 0.4, ease: "power3.inOut" }, T + 0.1);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```
@@ -0,0 +1,37 @@
+## Radial / Shape
+
+### Circle Iris
+
+Expanding circle from center reveals new scene.
+
+```js
+tl.set(new, { opacity: 1 }, T);
+tl.fromTo(new,
+  { clipPath: "circle(0% at 50% 50%)" },
+  { clipPath: "circle(75% at 50% 50%)", duration: 0.5, ease: "power2.out" }, T);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```
+
+### Diamond Iris
+
+Expanding diamond shape from center.
+
+```js
+tl.set(new, { opacity: 1 }, T);
+tl.fromTo(new,
+  { clipPath: "polygon(50% 50%, 50% 50%, 50% 50%, 50% 50%)" },
+  { clipPath: "polygon(50% -20%, 120% 50%, 50% 120%, -20% 50%)", duration: 0.5, ease: "power2.out" }, T);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```
+
+### Diagonal Split
+
+Old scene shrinks to a triangle in one corner.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10, clipPath: "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)" }, T);
+tl.to(old, { clipPath: "polygon(60% 0%, 100% 0%, 100% 40%, 60% 0%)", duration: 0.5, ease: "power3.inOut" }, T);
+tl.set(old, { opacity: 0, zIndex: "auto", clipPath: "none" }, T + 0.5);
+tl.set(new, { zIndex: "auto" }, T + 0.5);
+```
@@ -0,0 +1,24 @@
+## Scale / Zoom
+
+### Zoom Through
+
+Old zooms past camera + blurs, new zooms in from behind.
+
+```js
+tl.to(old, { scale: 2.5, opacity: 0, filter: "blur(8px)", duration: 0.4, ease: "power3.in" }, T);
+tl.fromTo(new,
+  { scale: 0.5, opacity: 0, filter: "blur(8px)" },
+  { scale: 1, opacity: 1, filter: "blur(0px)", duration: 0.4, ease: "power3.out" }, T + 0.15);
+```
+
+### Zoom Out
+
+Old shrinks away, new was behind it. Needs z-index management.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10, transformOrigin: "50% 50%" }, T);
+tl.to(old, { scale: 0.3, opacity: 0, duration: 0.4, ease: "power3.in" }, T);
+tl.set(old, { zIndex: "auto" }, T + 0.4);
+tl.set(new, { zIndex: "auto" }, T + 0.4);
+```
@@ -0,0 +1,75 @@
+# Text-to-Speech
+
+Generate speech audio locally using Kokoro-82M (no API key, runs on CPU).
+
+## Voice Selection
+
+Match voice to content. Default is `af_heart`.
+
+| Content type  | Voice                 | Why                        |
+| ------------- | --------------------- | -------------------------- |
+| Product demo  | `af_heart`/`af_nova`  | Warm, professional         |
+| Tutorial      | `am_adam`/`bf_emma`   | Neutral, easy to follow    |
+| Marketing     | `af_sky`/`am_michael` | Energetic or authoritative |
+| Documentation | `bf_emma`/`bm_george` | Clear British English      |
+| Casual        | `af_heart`/`af_sky`   | Approachable, natural      |
+
+Run `npx hyperframes tts --list` for all 54 voices (8 languages).
+
+## Multilingual Phonemization
+
+Kokoro voice IDs encode language in the first letter: `a`=American English, `b`=British English, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin. The CLI auto-detects the phonemizer locale from that prefix — you don't need to pass `--lang` when the voice matches the text.
+
+```bash
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
+```
+
+Use `--lang` only to override auto-detection (e.g. stylized accents):
+
+```bash
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+```
+
+Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`.
+
+Non-English phonemization requires `espeak-ng` installed system-wide (`brew install espeak-ng` on macOS, `apt-get install espeak-ng` on Debian/Ubuntu).
+
+## Speed Tuning
+
+- **0.7-0.8** — Tutorial, complex content
+- **1.0** — Natural pace (default)
+- **1.1-1.2** — Intros, upbeat content
+- **1.5+** — Rarely appropriate
+
+## Usage
+
+```bash
+npx hyperframes tts "Your script here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma --output narration.wav
+```
+
+In compositions:
+
+```html
+<audio
+  id="narration"
+  data-start="0"
+  data-duration="auto"
+  data-track-index="2"
+  src="narration.wav"
+  data-volume="1"
+></audio>
+```
+
+## TTS + Captions Workflow
+
+```bash
+npx hyperframes tts script.txt --voice af_heart --output narration.wav
+npx hyperframes transcribe narration.wav  # → transcript.json with word-level timestamps
+```
+
+## Requirements
+
+- Python 3.8+ with `kokoro-onnx` and `soundfile`
+- Model downloads on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`)
@@ -0,0 +1,175 @@
+# Typography
+
+The compiler embeds supported fonts — just write `font-family` in CSS.
+
+## Banned
+
+Training-data defaults that every LLM reaches for. These produce monoculture across compositions.
+
+Inter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata, Syne
+
+**Syne in particular** is the most overused "distinctive" display font. It is an instant AI design tell.
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **Don't pair two sans-serifs.** You do this constantly — one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.
+- **One expressive font per scene.** You pick two interesting fonts trying to make it "better." One performs, one recedes.
+- **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.
+- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.
+
+## What You Don't Do Without Being Told
+
+- **Tension should mean something.** Don't pattern-match pairings. Ask WHY these two fonts disagree. The pairing should embody the content's contradiction — mechanical vs human, public vs private, institutional vs personal. If you can't articulate the tension, it's arbitrary.
+- **Register switching.** Assign different fonts to different communicative modes — one voice for statements, another for data, another for attribution. Not hierarchy on a page. Voices in a conversation.
+- **Tension can live inside a single font.** A font that looks familiar but is secretly strange creates tension with the viewer's expectations, not with another font.
+- **One variable changed = dramatic contrast.** Same letterforms, monospaced vs proportional. Same family at different optical sizes. Changing only rhythm while everything else stays constant.
+- **Double personality works.** Two expressive fonts can coexist if they share an attitude (both irreverent, both precise) even when their forms are completely different.
+- **Time is hierarchy.** The first element to appear is the most important. In video, sequence replaces position.
+- **Motion is typography.** How a word enters carries as much meaning as the font. A 0.1s slam vs a 2s fade — same font, completely different message.
+- **Fixed reading time.** 3 seconds on screen = must be readable in 2. Fewer words, larger type.
+- **Tracking tighter than web.** -0.03em to -0.05em on display sizes. Video encoding compresses letter detail.
+
+## Finding Fonts
+
+Don't default to what you know. If the content is luxury, a grotesque sans might create more tension than the expected Didone serif. Decide the register first, then search.
+
+Save this script to `/tmp/fontquery.py` and run with `curl -s 'https://fonts.google.com/metadata/fonts' > /tmp/gfonts.json && python3 /tmp/fontquery.py /tmp/gfonts.json`:
+
+```python
+import json, sys, random
+from collections import OrderedDict
+
+random.seed()  # true random each run
+
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+fonts = data.get("familyMetadataList", [])
+
+ban = {"Inter","Roboto","Open Sans","Noto Sans","Lato","Poppins","Source Sans 3",
+       "PT Sans","Nunito","Outfit","Sora","Playfair Display","Cormorant Garamond",
+       "Bodoni Moda","EB Garamond","Cinzel","Prata","Arimo","Source Sans Pro","Syne"}
+skip_pfx = ("Roboto","Noto ","Google Sans","Bpmf","Playwrite","Anek","BIZ ",
+            "Nanum","Shippori","Sawarabi","Zen ","Kaisei","Kiwi ","Yuji ","Radio ")
+
+def ok(f):
+    if f["family"] in ban: return False
+    if any(f["family"].startswith(b) for b in skip_pfx): return False
+    if "latin" not in (f.get("subsets") or []): return False
+    return True
+
+seen = set()
+R = OrderedDict()
+
+# Trending Sans — recent (2022+), popular (<300)
+R["Trending Sans"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") in ("Sans Serif","Display") and f.get("dateAdded","") >= "2022-01-01" and f.get("popularity",9999) < 300:
+        R["Trending Sans"].append(f); seen.add(f["family"])
+
+# Trending Serif — recent (2018+), popular (<600)
+R["Trending Serif"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Serif" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:
+        R["Trending Serif"].append(f); seen.add(f["family"])
+
+# Monospace — recent (2018+), popular (<600)
+R["Monospace"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Monospace" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:
+        R["Monospace"].append(f); seen.add(f["family"])
+
+# Impact & Condensed — heavy display fonts with 800+ weight
+R["Impact & Condensed"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    has_heavy = any(k in list(f.get("fonts",{}).keys()) for k in ("800","900"))
+    is_display = f.get("category") in ("Sans Serif","Display")
+    if has_heavy and is_display and f.get("popularity",9999) < 400:
+        R["Impact & Condensed"].append(f); seen.add(f["family"])
+
+# Script & Handwriting — popular (<300)
+R["Script & Handwriting"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Handwriting" and f.get("popularity",9999) < 300:
+        R["Script & Handwriting"].append(f); seen.add(f["family"])
+
+
+# Randomize the top 5 in each category so the LLM doesn't always pick the same first result
+for cat in R:
+    R[cat].sort(key=lambda x: x.get("popularity",9999))
+    top5 = R[cat][:5]
+    rest = R[cat][5:]
+    random.shuffle(top5)
+    R[cat] = top5 + rest
+limits = {"Trending Sans":15,"Trending Serif":12,"Monospace":8,
+          "Impact & Condensed":12,"Script & Handwriting":10}
+for cat in R:
+    items = R[cat][:limits.get(cat,10)]
+    if not items: continue
+    print(f"--- {cat} ({len(items)}) ---")
+    for ff in items:
+        var = "VAR" if ff.get("axes") else "   "
+        print(f'  {ff.get("popularity"):4d} | {var} | {ff["family"]}')
+    print()
+```
+
+Five categories: trending sans, trending serif, monospace, impact/condensed, script/handwriting. All dynamically filtered from Google Fonts metadata — no hardcoded font names. Cross classification boundaries when pairing.
+
+## Selection Thinking
+
+Don't pick fonts by category reflex (editorial → serif, tech → mono, modern → geometric sans). That's pattern matching, not design.
+
+1. **Name the register.** What voice is the content speaking in? Institutional authority? Personal confession? Technical precision? Casual irreverence? The register narrows the field more than the category.
+2. **Think physically.** Imagine the font as a physical object the brand could ship — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label inside a coat, a children's book printed on cheap newsprint, a tax form. Whichever physical object fits the register is pointing at the right _kind_ of typeface.
+3. **Reject your first instinct.** The first font that feels right is usually your training-data default for that register. If you picked it last time too, find something else.
+4. **Cross-check the assumption.** An editorial brief does NOT need a serif. A technical brief does NOT need a sans. A children's product does NOT need a rounded display font. The most distinctive choice often contradicts the category expectation.
+
+## Similar-Font Pairing
+
+Never pair two fonts that are similar but not identical — two geometric sans-serifs, two transitional serifs, two humanist sans. They create visual friction without clear hierarchy. The viewer senses something is "off" but can't articulate it. Either use one font at two weights, or pair fonts that contrast on multiple axes: serif + sans, condensed + wide, geometric + humanist.
+
+## Dark Backgrounds
+
+Light text on dark backgrounds creates two optical illusions you need to compensate for:
+
+- **Increased apparent weight.** Light-on-dark reads heavier than dark-on-light at the same `font-weight`. Use 350 instead of 400 for body text. Headlines are less affected because size compensates.
+- **Tighter apparent spacing.** Light halos around letterforms reduce perceived gaps. Increase `line-height` by 0.05-0.1 beyond your light-background value. For display sizes, add 0.01em `letter-spacing` to counteract.
+
+## OpenType Features for Data
+
+Most fonts ship with OpenType features that are off by default. Turn them on for data compositions:
+
+```css
+/* Tabular numbers — digits align vertically in columns */
+.stat-value,
+.timer,
+.data-column {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Diagonal fractions — renders 1/2 as ½ */
+.recipe-amount,
+.ratio {
+  font-variant-numeric: diagonal-fractions;
+}
+
+/* Small caps for abbreviations — less visual shouting */
+.abbreviation,
+.unit {
+  font-variant-caps: all-small-caps;
+}
+
+/* Disable ligatures in code — fi, fl, ffi should stay separate */
+code,
+.code {
+  font-variant-ligatures: none;
+}
+```
+
+`tabular-nums` is essential any time numbers are stacked vertically — stat callouts, timers, scoreboards, data tables. Without it, digits have proportional widths and columns don't align.