hyperframes 0.6.31 → 0.6.33

package/dist/skills/hyperframes/references/prompt-expansion.md

@@ -8,12 +8,12 @@ Runs AFTER design direction is established (Step 1). The expansion consumes desi
 
 Read before generating:
 
-- `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
+- `DESIGN.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
 - [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
 - [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
 - [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
 
-If `design.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
+If `DESIGN.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
 
 ## Why always run it
 
@@ -40,7 +40,7 @@ Expand into a full production prompt with these sections:
 
 1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
 
-2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. See [beat-direction.md](beat-direction.md) for rhythm templates by video type.
+2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. Derive the rhythm from the brand and the storyboard's emotional arc — see [beat-direction.md](beat-direction.md) for the considerations that drive this decision.
 
 3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
 

package/dist/skills/hyperframes/references/techniques.md

@@ -1,8 +1,34 @@
 # Visual Techniques Reference
 
-10 proven techniques from production HyperFrames videos. Use these in your storyboard and compositions to create visually rich, professional output. Each technique includes a minimal code pattern you can adapt.
+13 primitive animation techniques from production HyperFrames videos — SVG drawing, kinetic typography, variable fonts, WebGL shaders, motion-path, etc. Compose these into beats; they are the building blocks, not finished recipes. Each entry includes a minimal code pattern you can adapt.
 
-These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of.
+These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of. For pre-built UI templates (terminal chrome, device mockups, moodboard layouts), look in the `registry/blocks/` directory instead — those are recipes, not techniques.
+
+**These are starting points, not copy-paste templates.** Every code pattern below is a minimal working example from a real production video. Adapt them to your needs — change colors, sizes, timings, easings, element counts, layout. Combine techniques, mix parts from different patterns, invent variations. The goal is to understand the PRINCIPLE behind each technique so you can build something original, not to reproduce these examples exactly.
+
+## Table of Contents
+
+**Named text animation effects** (per-character, per-word, per-line, whole-element) — 24 effects with exact GSAP specs come from the separate `pixel-point/animate-text` skill. See [`text-effects.md`](text-effects.md) for the effect-name vocabulary and instructions for loading the upstream skill. Use those for all headline and label animations instead of inventing timing from scratch.
+
+**HTML-in-Canvas patterns** (live DOM as GPU texture: iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor — using `drawElementImage` + `layoutsubtree`) are in [`html-in-canvas-patterns.md`](html-in-canvas-patterns.md) — 504 lines, one shared boilerplate + ~6 effect recipes. Use for 1–3 hero beats per video, not every beat.
+
+---
+
+| #   | Technique                         | What it does                                                               | Best for                                       |
+| --- | --------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- |
+| 1   | **SVG Path Drawing**              | Logos/icons draw themselves stroke by stroke                               | Logo reveals, diagram builds, connector lines  |
+| 2   | **Canvas 2D Procedural Art**      | Animated noise, particles, data viz — frame-by-frame via GSAP proxy        | Generative backgrounds, ambient texture        |
+| 3   | **CSS 3D Transforms**             | Card flips, perspective grids, folding panels                              | Product reveals, comparison scenes             |
+| 4   | **Per-Word Kinetic Typography**   | Text animates word-by-word with stagger timing                             | Thesis statements, key messages, quotes        |
+| 5   | **Lottie Animation**              | Captured or external Lottie plays as overlay/background                    | Brand animations, micro-interactions           |
+| 6   | **Video Compositing**             | Product videos play inline, masked, overlaid                               | Demo footage, screen recordings                |
+| 7   | **Character-by-Character Typing** | Terminal-style code reveals, search bar interactions                       | Developer tools, CLI demos                     |
+| 8   | **Variable Font Axis Animation**  | Weight, width, slant, optical size morph over time                         | Premium typography, brand wordmarks            |
+| 9   | **GSAP MotionPathPlugin**         | Elements follow SVG curves, orbital motion, spirals                        | Dynamic entrances, connector animations        |
+| 10  | **Velocity-Matched Transitions**  | Outgoing blur/translate matches incoming for seamless cuts                 | Beat transitions, scene changes                |
+| 11  | **Audio-Reactive Animation**      | Elements pulse to narration frequency bands                                | Background textures, text glow, ambient motion |
+| 12  | **Clip-Path Reveal Masks**        | Fixed window that content slides through (text/images enter from one side) | Headline intros, image reveals, wipe effects   |
+| 13  | **WebGL Fragment Shader Art**     | Full GPU generative backgrounds — FBM domain warp, cosine palettes         | Hero backgrounds, atmospheric scenes           |
 
 ---
 
@@ -155,16 +181,22 @@ The slide distance DECAYS per word (80→12px) — mimics a camera settling.
 Vector animations that play inside a composition. Use for logos, character animations, icons.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@dotlottie/player-component@2.7.12/dist/dotlottie-player.js"></script>
-<dotlottie-player
+<!-- The web-component package is `@lottiefiles/dotlottie-wc` (the SDK
+     `@lottiefiles/dotlottie-web` does NOT expose a custom element).
+     The element tag is <dotlottie-wc>. -->
+<script
+  src="https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-wc/dist/dotlottie-wc.js"
+  type="module"
+></script>
+<dotlottie-wc
   class="lottie"
-  src="../capture/assets/lottie/animation-0.json"
+  src="capture/assets/lottie/animation-0.json"
   autoplay
   loop
   speed="1.5"
   style="width:500px;height:500px;"
 >
-</dotlottie-player>
+</dotlottie-wc>
 <script>
   gsap.set(".lottie", { scale: 0.3, opacity: 0 });
   tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
@@ -179,7 +211,7 @@ var anim = lottie.loadAnimation({
   renderer: "svg",
   loop: false,
   autoplay: false,
-  path: "../capture/assets/lottie/animation-0.json",
+  path: "capture/assets/lottie/animation-0.json",
 });
 ```
 
@@ -193,7 +225,7 @@ Embed real video footage inside compositions. Videos must be `muted` with `plays
 <div class="video-frame" style="width:680px;height:840px;border-radius:16px;overflow:hidden;">
   <video
     id="footage"
-    src="../capture/assets/videos/clip.mp4"
+    src="capture/assets/videos/clip.mp4"
     muted
     playsinline
     style="width:100%;height:100%;object-fit:cover;"
@@ -252,10 +284,10 @@ Animate font-variation-settings to reshape glyphs in real-time. Works with varia
 ```html
 <style>
   /* Load the captured local variable font — do NOT use Google Fonts @import.
-     Replace this placeholder with an @font-face pointing to ../capture/assets/fonts/. */
+     Replace this placeholder with an @font-face pointing to capture/assets/fonts/. */
   @font-face {
     font-family: "Fraunces";
-    src: url("../capture/assets/fonts/Fraunces-Variable.woff2") format("woff2");
+    src: url("capture/assets/fonts/Fraunces-Variable.woff2") format("woff2");
     font-weight: 100 900;
     font-style: normal;
     font-display: block;
@@ -317,7 +349,7 @@ tl.to(
     duration: 0.33,
     ease: "power2.in", // accelerates
   },
-  beatDuration - 0.33,
+  parseFloat(root.dataset.duration) - 0.33, // start exit 0.33s before beat ends
 );
 
 // ENTRY (in incoming composition): decelerating from blur
@@ -376,12 +408,133 @@ Keep text/logo intensity subtle (≤5% scale, ≤30% glow) — audio-reactive mo
 
 ---
 
-## When to Use What
+## 12. Clip-Path Reveal Masks
+
+A fixed window that content slides through — text or images enter from one side and are clipped by an invisible boundary. Different from SVG path drawing: the mask is static, the content moves.
+
+```html
+<div id="reveal-mask">
+  <div id="reveal-content">Your headline text here</div>
+</div>
+<style>
+  #reveal-mask {
+    position: absolute;
+    inset: 0;
+    clip-path: inset(0 200px 0 0); /* clips 200px from right */
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  #reveal-content {
+    font-size: 108px;
+    white-space: nowrap;
+  }
+</style>
+<script>
+  // Content starts offscreen right, slides left through the mask window
+  gsap.set("#reveal-content", { x: 400, opacity: 0 });
+  tl.to("#reveal-content", { x: 0, opacity: 1, duration: 1, ease: "power2.out" }, 0);
+</script>
+```
+
+Variations: `clip-path: circle(0% at 50% 50%)` → `circle(100%)` for iris reveals. `clip-path: polygon(...)` for custom shapes.
+
+---
+
+## 13. WebGL Fragment Shader Art
+
+Full GPU generative backgrounds — domain-warped FBM noise, cosine palette coloring, iridescent organic patterns. Far richer than Canvas 2D.
+
+```html
+<canvas id="shader-bg" width="1920" height="1080"></canvas>
+<script>
+  var canvas = document.getElementById("shader-bg");
+  var gl = canvas.getContext("webgl");
+  if (!gl) {
+    /* fallback to gradient */
+  }
+
+  var fsrc = `
+    precision mediump float;
+    varying vec2 v_uv;
+    uniform float u_time;
+    uniform vec2 u_res;
+
+    float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+    float noise(vec2 p) {
+      vec2 i = floor(p), f = fract(p);
+      f = f * f * (3.0 - 2.0 * f);
+      return mix(mix(hash(i), hash(i+vec2(1,0)), f.x),
+                 mix(hash(i+vec2(0,1)), hash(i+vec2(1,1)), f.x), f.y);
+    }
+    float fbm(vec2 p) {
+      float v = 0.0, a = 0.5;
+      mat2 R = mat2(0.8, 0.6, -0.6, 0.8);
+      for (int i = 0; i < 5; i++) { v += a*noise(p); p = R*p*2.02; a *= 0.5; }
+      return v;
+    }
+    vec3 palette(float t) {
+      return vec3(0.5)+vec3(0.5)*cos(6.28318*(vec3(1)*t+vec3(0.0,0.33,0.67)));
+    }
+    void main() {
+      vec2 uv = v_uv; uv.x *= u_res.x/u_res.y;
+      float t = u_time * 0.4;
+      vec2 q = vec2(fbm(uv*3.0+t*0.3), fbm(uv*3.0+vec2(5.2,1.3)+t*0.2));
+      vec2 r = vec2(fbm(uv*3.0+q*4.0+vec2(1.7,9.2)+t*0.15), fbm(uv*3.0+q*4.0+vec2(8.3,2.8)+t*0.1));
+      float n = fbm(uv*3.0+r*2.0);
+      vec3 col = palette(n*2.0+t*0.2);
+      col = mix(col, palette(length(q)*3.0+t*0.1), 0.4);
+      col *= 0.7+0.3*n;
+      float vig = 1.0-0.4*length(v_uv-0.5);
+      gl_FragColor = vec4(col*vig, 1.0);
+    }
+  `;
+
+  // Compile, link, set up fullscreen quad, then render via GSAP proxy:
+  var proxy = { time: 0.5 };
+  tl.to(
+    proxy,
+    {
+      time: 5,
+      duration: BEAT_DUR,
+      ease: "none",
+      onUpdate: function () {
+        gl.uniform1f(uTime, proxy.time);
+        gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+      },
+    },
+    0,
+  );
+</script>
+```
+
+Always include a Canvas 2D gradient fallback for environments without WebGL.
+
+---
+
+## Easing Vocabulary
+
+GSAP offers a deep easing library. Every composition should use at least 3 different easings — using `power2.out` for everything produces flat, monotonous motion. Think of easings as tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging.
+
+**The full palette** (each family has `.in`, `.out`, `.inOut` variants):
+
+| Family               | Character                                                                    | Typical use                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. power2 is the workhorse, power4 for dramatic snaps                                |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Logo reveals, badge pops, card entrances. `back.out(2.5)` for playful, `back.out(1.2)` for elegant |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Panel scatter, energetic drops, fun reveals                                                        |
+| `bounce`             | Ball-drop bouncing                                                           | Physical interactions, icons landing, score counters                                               |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                         |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                 |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                    |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                              |
+
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical. The storyboard's mood description should guide which character fits — not a formula.
+
+---
+
+## Choosing techniques
+
+Don't match techniques to video type on autopilot — match them to the **concept of the specific beat**. Ask: what visual treatment makes this exact idea land? A beat about speed needs motion that communicates speed; a beat about precision needs geometry and structure; a beat about warmth needs texture and organic drift.
 
-| Video energy                   | Techniques to combine                                           |
-| ------------------------------ | --------------------------------------------------------------- |
-| High impact (launches, promos) | Per-word typography + velocity transitions + counter animations |
-| Cinematic (tours, stories)     | SVG path drawing + video compositing + 3D transforms            |
-| Technical (dev tools, APIs)    | Character typing + Canvas 2D procedural + MotionPath            |
-| Premium (luxury, enterprise)   | Variable font animation + Lottie + slow velocity transitions    |
-| Data-driven (stats, metrics)   | Canvas 2D procedural + counter animations + SVG path drawing    |
+Read the storyboard beat's concept and mood, then scan this list for techniques whose _visual character_ serves that concept. Any technique can appear in any video type — the question is whether it earns its place in this beat.

package/dist/skills/hyperframes/references/text-effects.md

@@ -0,0 +1,64 @@
+# Text Effects — Reference
+
+For deterministic text-animation specs (e.g., `typewriter` at exact `240ms / 46ms stagger / steps(1, end) easing`), this skill defers to the separate **`animate-text`** skill maintained by Pixel Point at [github.com/pixel-point/animate-text](https://github.com/pixel-point/animate-text). It provides a catalog of 24 named text effects with portable contracts and per-library implementation recipes (GSAP, Anime.js, WAAPI).
+
+**We do NOT ship the catalog inside this repo.** Pixel Point's `animate-text` is the source of truth; vendoring its files here would violate the upstream's licensing (no explicit license declared upstream as of this writing). Loading the skill separately keeps the legal picture clean while giving you the same catalog.
+
+## How to use it
+
+When a beat needs a deterministic text animation, load the upstream skill alongside this one:
+
+```bash
+# In your project root, install the upstream skill into .agents/skills/
+npx skills add pixel-point/animate-text
+```
+
+Or in Claude Code / a skill-aware agent runtime, the skill is invoked by name:
+
+```
+/animate-text
+```
+
+Once installed, the specs live at:
+
+```
+.agents/skills/animate-text/assets/effects/<id>.json   # per-library implementation recipe
+.agents/skills/animate-text/assets/specs/<id>.json     # portable motion contract
+```
+
+Sub-agents reading those files get exact GSAP timings, easing strings, DOM split rules, and stagger algorithms — no creative invention needed.
+
+## When you don't need the upstream skill
+
+If a beat's text animation is simple enough to describe in prose ("headline fades up word-by-word, 80ms stagger"), implement it inline using the GSAP knowledge already in this skill ([motion-principles.md](motion-principles.md), [beat-direction.md](beat-direction.md), [techniques.md](techniques.md) — see entry #4 "Per-Word Kinetic Typography"). The upstream catalog is most valuable when:
+
+- You want a specific NAMED effect across multiple beats (so they feel like one design system, not one-offs)
+- You're choosing between several similar effects (typewriter vs per-character-rise vs bottom-up-letters) and want to see all 24 in one place
+- You need layout-aware effects (`kinetic-center-build`, `short-slide-right`, `short-slide-down`) where parameters alone aren't enough — those ship with custom layout algorithms
+
+## Effect names — vocabulary (do NOT use this as the implementation source)
+
+For convenience while writing storyboards: the upstream skill provides 24 effects. Their IDs are listed here so you can name them in `STORYBOARD.md` even before loading the upstream skill. **The implementation specs are in the upstream skill, not here.**
+
+- **Per-character (7):** soft-blur-in, per-character-rise, typewriter, bottom-up-letters, top-down-letters, stagger-from-center, stagger-from-edges
+- **Per-word (8):** per-word-crossfade, spring-scale-in, shared-axis-y, blur-out-up, kinetic-center-build, short-slide-right, short-slide-down, depth-parallax-words
+- **Per-line (2):** mask-reveal-up, line-by-line-slide
+- **Whole element (7):** micro-scale-fade, shimmer-sweep, fade-through, shared-axis-z, scale-down-fade, focus-blur-resolve, shared-axis-x
+
+For descriptions, durations, easing curves, and the per-library recipes: load `/animate-text` and read its own catalog page.
+
+## In the storyboard
+
+Every text element in every beat can name an effect by ID, e.g.:
+
+```markdown
+**Text Animations:**
+
+- Main headline: `kinetic-center-build`
+- Eyebrow label: `soft-blur-in`
+- Body copy 3 lines: `mask-reveal-up`
+```
+
+Sub-agents implementing the beat will load `/animate-text` if it's not already loaded, then read the spec for each named effect from the upstream skill's files.
+
+If the upstream skill isn't available (offline build, network restrictions, agent runtime that doesn't support skill loading), sub-agents fall back to implementing the effect from the description alone — using GSAP knowledge plus the effect ID as a description of intent (e.g., "typewriter" = per-character stepped reveal with no interpolation).

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

@@ -11,50 +11,61 @@ These are non-negotiable for every multi-scene composition:
 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 → Transition Character
 
-| 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`       |
+The energy of a beat tells you what motion character the transition should have — not which specific transition to use. The motion character is a quality you derive from the brand and content, then find a transition that has that quality.
 
-Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
+**Soft/organic character:** transitions that breathe, dissolve, or drift. Nothing sharp, mechanical, or percussive. Duration 0.5–0.8s, smooth easing curves.
 
-## Mood → Transition Type
+**Directional/purposeful character:** transitions that move content decisively. Clear direction, readable momentum. Duration 0.3–0.5s, clean deceleration.
 
-Think about what the transition _communicates_, not just what it looks like.
+**Percussive/instant character:** transitions that hit like a cut. Immediate, almost hard-cut energy. Duration 0.15–0.3s, aggressive or near-instant easing.
 
-| 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.                            |
+These are calibration ranges, not recipes. A brand that treats its "high energy" section with restraint might use 0.4s for a moment that another brand transitions in 0.2s — both are correct for their brand. Pick ONE character that defines the video's primary transitions, then use 1–2 contrasting moments as intentional accents. See the **Mood → Motion Quality** section below to find transitions with the right character for a given mood.
+
+## Mood → Motion Quality
+
+Think about what the transition _communicates_, not what it looks like. The question is: **what motion quality serves this mood?** Then find transitions that have that quality in the catalog (`transitions/catalog.md`).
+
+| Mood                     | Motion quality that fits                                                                    | Why                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Warm / inviting**      | Soft edges, dissolving, color-temperature washes — nothing sharp, mechanical, or percussive | Warmth reads as continuity and flow; hard cuts or compression feel cold             |
+| **Cold / clinical**      | Mechanical transformation — compression, slicing, gridding, precision                       | The content appears to be processed or structured, reinforcing a systematic quality |
+| **Editorial / magazine** | Clean directional movement — like turning a page                                            | Feels like content is being browsed or curated, not revealed                        |
+| **Tech / futuristic**    | Data-like fragmentation, digital displacement, scan artifacts                               | Transition feels computational rather than physical                                 |
+| **Tense / edgy**         | Instability, distortion, displacement — something slightly wrong about the image            | Introduces friction where smooth transitions would release tension                  |
+| **Playful / fun**        | Overshoot, expansion, rotation — motion with personality and bounce                         | Transitions that feel like objects rather than effects                              |
+| **Dramatic / cinematic** | Scale, weight, light extremes — the cut is an event, not a bridge                           | Every shader and every hard cut carries narrative gravity                           |
+| **Premium / luxury**     | Restraint — transitions that are barely visible, or invisible                               | Luxury communicates through what it withholds                                       |
+| **Retro / analog**       | Organic imperfection — light bleed, scan lines, color wash                                  | Physical film artifacts; imperfection as authenticity                               |
+
+Use this table to derive what **quality** the transition should have, then look at the specific options in `transitions/catalog.md` to find one that has that quality for this brand. The transitions listed in the catalog are all available; none are reserved for a specific mood.
 
 ## 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.       |
+Each position in the video has a different job to do. What transition you pick for each should come from the brand's motion character and the storyboard's intent — not from a rule about "climax = boldest."
+
+- **Opening** — establishes the motion language for the entire video. Make a deliberate choice; whatever you pick here sets the viewer's expectation for everything that follows.
+- **Between related points** — should be almost invisible. The content is continuing; the transition shouldn't draw attention to itself. Consistency matters more than distinctiveness here.
+- **Topic change** — needs enough contrast from your primary that it signals "something different is starting." The contrast is in motion character, not just duration.
+- **Climax / hero reveal** — this is the moment the video has been building to. The transition should feel earned by what came before. "Use your boldest transition here" is a default, not a rule — the climax of a restrained editorial piece might be a hard cut.
+- **Wind-down** — returns to a motion character that allows the viewer to exhale. Matches the opening in tone, not necessarily in technique.
+- **Outro** — no new energy. Slowest and simplest in the video. Closure.
+
+## Blur and Motion Intensity
+
+Blur and duration should express the energy of the content, not match a lookup table. The ranges below are calibration references — starting points to adjust from based on what the brand and storyboard call for.
+
+Higher-energy transitions: shorter duration, less blur, no hold at peak. The motion is immediate.
+Lower-energy transitions: longer duration, more blur, longer hold at peak. The motion has weight.
+
+Calibration ranges (not prescriptions):
 
-## Blur Intensity by Energy
+- Soft/organic: blur 20–30px, duration 0.8–1.2s, hold 0.3–0.5s
+- Directional/purposeful: blur 8–15px, duration 0.4–0.6s, hold 0.1–0.2s
+- Percussive/instant: blur 3–6px, duration 0.2–0.3s, no hold
 
-| 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           |
+A brand that uses these as a formula will produce transitions that feel the same across every video. A brand-derived choice asks: what blur and duration expresses the weight this transition should have?
 
 ## Presets
 
@@ -92,7 +103,22 @@ CSS transitions animate scene containers with opacity, transforms, clip-path, an
 
 **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.
+**Mixing is supported.** You can have some transitions use WebGL shaders and others use a CSS crossfade in the same composition. Omit the `shader` field on any `TransitionConfig` entry to get a smooth opacity crossfade instead of a WebGL effect:
+
+```js
+var tl = HyperShader.init({
+  bgColor: "#000",
+  accentColor: "#6366f1",
+  scenes: ["s1", "s2", "s3", "s4"],
+  transitions: [
+    { time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader
+    { time: 8.5, duration: 0.8 }, // no shader → CSS crossfade
+    { time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader
+  ],
+});
+```
+
+HyperShader manages all scene visibility regardless of transition type. Let it create the timeline (don't pass `timeline:` into `init()`) and add your beat animations to the returned `tl` after the call.
 
 ## Shader-Compatible CSS Rules