From 66e815dff33addd3143fe083ea42d79cdb02afe1 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Mon, 6 Apr 2026 13:30:09 -0700
Subject: [PATCH] refactor(skills): fold transitions into hyperframes skill

Move transitions from a standalone skill (4th top-level) into
hyperframes/references/transitions/, aligning with the consolidation
in #211 that reduced 15 skills to 3. Fewer standalone skills means
higher trigger reliability for multi-skill tasks.

Also removes stale text-burn-dom.html reference from css-destruction.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 skills/hyperframes/SKILL.md                   |  7 +++-
 .../references/transitions.md}                |  9 +----
 .../references}/transitions/catalog.md        | 40 +++++++++----------
 .../references/transitions}/css-3d.md         |  0
 .../references/transitions}/css-blur.md       |  0
 .../references/transitions}/css-cover.md      |  0
 .../transitions}/css-destruction.md           |  4 +-
 .../references/transitions}/css-dissolve.md   |  0
 .../references/transitions}/css-distortion.md |  0
 .../references/transitions}/css-grid.md       |  0
 .../references/transitions}/css-light.md      |  0
 .../references/transitions}/css-mechanical.md |  0
 .../references/transitions}/css-other.md      |  0
 .../references/transitions}/css-push.md       |  0
 .../references/transitions}/css-radial.md     |  0
 .../references/transitions}/css-scale.md      |  0
 .../references/transitions}/shader-setup.md   |  0
 .../transitions}/shader-transitions.md        |  0
 18 files changed, 29 insertions(+), 31 deletions(-)
 rename skills/{transitions/SKILL.md => hyperframes/references/transitions.md} (95%)
 rename skills/{ => hyperframes/references}/transitions/catalog.md (84%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-3d.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-blur.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-cover.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-destruction.md (94%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-dissolve.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-distortion.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-grid.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-light.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-mechanical.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-other.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-push.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-radial.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/css-scale.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/shader-setup.md (100%)
 rename skills/{transitions/references => hyperframes/references/transitions}/shader-transitions.md (100%)

diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 979794ca5..7ef2fa557 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: hyperframes
-description: Create video compositions, animations, title cards, overlays, captions, voiceovers, and audio-reactive visuals in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), or add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.
+description: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.
 ---
 
 # HyperFrames
@@ -147,4 +147,9 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 - **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting.
 - **[references/dynamic-techniques.md](references/dynamic-techniques.md)** — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).
 
+- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, narrative position, CSS vs WebGL guidance. Read when a composition has multiple scenes that need visual handoffs.
+  - [transitions/catalog.md](references/transitions/catalog.md) — Hard rules, scene template, and routing to per-type implementation code.
+  - [transitions/shader-setup.md](references/transitions/shader-setup.md) — WebGL boilerplate for shader transitions.
+  - [transitions/shader-transitions.md](references/transitions/shader-transitions.md) — 14 fragment shaders.
+
 GSAP patterns and effects are in the `/gsap` skill.
diff --git a/skills/transitions/SKILL.md b/skills/hyperframes/references/transitions.md
similarity index 95%
rename from skills/transitions/SKILL.md
rename to skills/hyperframes/references/transitions.md
index 579a851cc..624e6603f 100644
--- a/skills/transitions/SKILL.md
+++ b/skills/hyperframes/references/transitions.md
@@ -1,8 +1,3 @@
----
-name: transitions
-description: Use when a HyperFrames composition has multiple scenes that need transitions between them. Also use when the user mentions crossfades, wipes, reveals, scene changes, or when a composition feels like scenes just pop in and out without visual handoffs.
----
-
 # Scene Transitions
 
 A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A flash cut says "wake up." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
@@ -65,7 +60,7 @@ Think about what the transition _communicates_, not just what it looks like.
 
 ## Implementation
 
-Read [catalog.md](./catalog.md) for GSAP code and hard rules for every transition type.
+Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
 
 | Category             | Transitions                                                                                                                                                                                                           |
 | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -94,7 +89,7 @@ Most compositions should use **CSS/GSAP transitions** (the other categories abov
 | No images/video in scenes (text + shapes only) | Live video needs to play through the transition |
 | Quick to set up, no boilerplate                | Willing to add WebGL setup layer (~200 lines)   |
 
-Shader transitions require setup boilerplate (canvas, scene capture, WebGL init). Read [references/shader-setup.md](./references/shader-setup.md) for the complete code. The fragment shaders themselves are in the Shader section of [catalog.md](./catalog.md).
+Shader transitions require setup boilerplate (canvas, scene capture, WebGL init). Read [transitions/shader-setup.md](transitions/shader-setup.md) for the complete code. The fragment shaders themselves are in the Shader section of [transitions/catalog.md](transitions/catalog.md).
 
 ## Visual Pattern Warning
 
diff --git a/skills/transitions/catalog.md b/skills/hyperframes/references/transitions/catalog.md
similarity index 84%
rename from skills/transitions/catalog.md
rename to skills/hyperframes/references/transitions/catalog.md
index 5225b136b..b69c412c9 100644
--- a/skills/transitions/catalog.md
+++ b/skills/hyperframes/references/transitions/catalog.md
@@ -30,7 +30,7 @@ These cause real bugs if violated.
 
 ## Hard Rules (Shader)
 
-Read [references/shader-setup.md](./references/shader-setup.md) for the full setup code these rules apply to.
+Read [shader-setup.md](./shader-setup.md) for the full setup code these rules apply to.
 
 **WebGL setup:** `gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false)` — NOT true. Vertex shader flips Y: `v_uv.y = 1.0 - v_uv.y`. `preserveDrawingBuffer: true` required for HyperFrames capture. No `fwidth()` without extension — use constant `0.003`.
 
@@ -106,27 +106,27 @@ Every transition follows: position new scene → animate outgoing → swap → a
 
 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](./references/css-push.md)               |
-| Radial / Shape | Circle iris, diamond iris, diagonal split            | [css-radial.md](./references/css-radial.md)           |
-| 3D             | 3D card flip                                         | [css-3d.md](./references/css-3d.md)                   |
-| Scale / Zoom   | Zoom through, zoom out                               | [css-scale.md](./references/css-scale.md)             |
-| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | [css-dissolve.md](./references/css-dissolve.md)       |
-| Cover          | Staggered blocks, horizontal blinds, vertical blinds | [css-cover.md](./references/css-cover.md)             |
-| Light          | Light leak, overexposure burn, film burn             | [css-light.md](./references/css-light.md)             |
-| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | [css-distortion.md](./references/css-distortion.md)   |
-| Mechanical     | Shutter, clock wipe                                  | [css-mechanical.md](./references/css-mechanical.md)   |
-| Grid           | Grid dissolve                                        | [css-grid.md](./references/css-grid.md)               |
-| Other          | Flash cut, gravity drop, morph circle                | [css-other.md](./references/css-other.md)             |
-| Blur           | Blur through, directional blur                       | [css-blur.md](./references/css-blur.md)               |
-| Destruction    | Page burn                                            | [css-destruction.md](./references/css-destruction.md) |
+| 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          | Flash cut, 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 fragment shaders that composite between scene textures per-pixel. Require setup boilerplate.
 
-| What                                                                                                                                                                                                                                            | Reference                                                   |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| Setup (canvas, capture, WebGL init, render loop, GSAP integration)                                                                                                                                                                              | [shader-setup.md](./references/shader-setup.md)             |
-| Fragment shaders (14 transitions: domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak) | [shader-transitions.md](./references/shader-transitions.md) |
+| What                                                                                                                                                                                                                                            | Reference                                        |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Setup (canvas, capture, WebGL init, render loop, GSAP integration)                                                                                                                                                                              | [shader-setup.md](./shader-setup.md)             |
+| Fragment shaders (14 transitions: domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak) | [shader-transitions.md](./shader-transitions.md) |
diff --git a/skills/transitions/references/css-3d.md b/skills/hyperframes/references/transitions/css-3d.md
similarity index 100%
rename from skills/transitions/references/css-3d.md
rename to skills/hyperframes/references/transitions/css-3d.md
diff --git a/skills/transitions/references/css-blur.md b/skills/hyperframes/references/transitions/css-blur.md
similarity index 100%
rename from skills/transitions/references/css-blur.md
rename to skills/hyperframes/references/transitions/css-blur.md
diff --git a/skills/transitions/references/css-cover.md b/skills/hyperframes/references/transitions/css-cover.md
similarity index 100%
rename from skills/transitions/references/css-cover.md
rename to skills/hyperframes/references/transitions/css-cover.md
diff --git a/skills/transitions/references/css-destruction.md b/skills/hyperframes/references/transitions/css-destruction.md
similarity index 94%
rename from skills/transitions/references/css-destruction.md
rename to skills/hyperframes/references/transitions/css-destruction.md
index 7f095df81..9229cffc4 100644
--- a/skills/transitions/references/css-destruction.md
+++ b/skills/hyperframes/references/transitions/css-destruction.md
@@ -92,6 +92,4 @@ 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`.
 
-**Note:** This is the most complex transition in the catalog. Reference the full implementation at `text-burn-dom.html` for the complete standalone example.
-
-See `/Users/vanceingalls/src/claude/text-burn-dom.html` for the complete standalone implementation.
+The `onUpdate` callback is the key — it runs every frame to advance the clip-path and canvas edge in sync with the timeline.
diff --git a/skills/transitions/references/css-dissolve.md b/skills/hyperframes/references/transitions/css-dissolve.md
similarity index 100%
rename from skills/transitions/references/css-dissolve.md
rename to skills/hyperframes/references/transitions/css-dissolve.md
diff --git a/skills/transitions/references/css-distortion.md b/skills/hyperframes/references/transitions/css-distortion.md
similarity index 100%
rename from skills/transitions/references/css-distortion.md
rename to skills/hyperframes/references/transitions/css-distortion.md
diff --git a/skills/transitions/references/css-grid.md b/skills/hyperframes/references/transitions/css-grid.md
similarity index 100%
rename from skills/transitions/references/css-grid.md
rename to skills/hyperframes/references/transitions/css-grid.md
diff --git a/skills/transitions/references/css-light.md b/skills/hyperframes/references/transitions/css-light.md
similarity index 100%
rename from skills/transitions/references/css-light.md
rename to skills/hyperframes/references/transitions/css-light.md
diff --git a/skills/transitions/references/css-mechanical.md b/skills/hyperframes/references/transitions/css-mechanical.md
similarity index 100%
rename from skills/transitions/references/css-mechanical.md
rename to skills/hyperframes/references/transitions/css-mechanical.md
diff --git a/skills/transitions/references/css-other.md b/skills/hyperframes/references/transitions/css-other.md
similarity index 100%
rename from skills/transitions/references/css-other.md
rename to skills/hyperframes/references/transitions/css-other.md
diff --git a/skills/transitions/references/css-push.md b/skills/hyperframes/references/transitions/css-push.md
similarity index 100%
rename from skills/transitions/references/css-push.md
rename to skills/hyperframes/references/transitions/css-push.md
diff --git a/skills/transitions/references/css-radial.md b/skills/hyperframes/references/transitions/css-radial.md
similarity index 100%
rename from skills/transitions/references/css-radial.md
rename to skills/hyperframes/references/transitions/css-radial.md
diff --git a/skills/transitions/references/css-scale.md b/skills/hyperframes/references/transitions/css-scale.md
similarity index 100%
rename from skills/transitions/references/css-scale.md
rename to skills/hyperframes/references/transitions/css-scale.md
diff --git a/skills/transitions/references/shader-setup.md b/skills/hyperframes/references/transitions/shader-setup.md
similarity index 100%
rename from skills/transitions/references/shader-setup.md
rename to skills/hyperframes/references/transitions/shader-setup.md
diff --git a/skills/transitions/references/shader-transitions.md b/skills/hyperframes/references/transitions/shader-transitions.md
similarity index 100%
rename from skills/transitions/references/shader-transitions.md
rename to skills/hyperframes/references/transitions/shader-transitions.md