dsh-hyperframes 0.1.0

package/skills/hyperframes/references/dynamic-techniques.md

@@ -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                                                        |

package/skills/hyperframes/references/motion-principles.md

@@ -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).

package/skills/hyperframes/references/transcript-guide.md

@@ -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.

package/skills/hyperframes/references/transitions/catalog.md

@@ -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.

package/skills/hyperframes/references/transitions/css-3d.md

@@ -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);
+```

package/skills/hyperframes/references/transitions/css-blur.md

@@ -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);
+```

package/skills/hyperframes/references/transitions/css-cover.md

@@ -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.

package/skills/hyperframes/references/transitions/css-destruction.md

@@ -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.