@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/hyperframes-creative/palettes/bold-energetic.md

@@ -0,0 +1,14 @@
+# Bold / Energetic
+
+Product launches, social media, announcements, high-energy content.
+
+```
+#FFBE0B #FB5607 #FF006E #8338EC #3A86FF
+#F72585 #7209B7 #3A0CA3 #4361EE #4CC9F0
+#EF476F #FFD166 #06D6A0 #118AB2 #073B4C
+#FF595E #FFCA3A #8AC926 #1982C4 #6A4C93
+#9B5DE5 #F15BB5 #FEE440 #00BBF9 #00F5D4
+#390099 #9E0059 #FF0054 #FF5400 #FFBD00
+#3D348B #7678ED #F7B801 #F18701 #F35B04
+#FFBC42 #D81159 #8F2D56 #218380 #73D2DE
+```

package/.agents/skills/hyperframes-creative/palettes/clean-corporate.md

@@ -0,0 +1,14 @@
+# Clean / Corporate
+
+Explainers, tutorials, presentations, professional content.
+
+```
+#FFFCF2 #CCC5B9 #403D39 #252422 #EB5E28
+#22223B #4A4E69 #9A8C98 #C9ADA7 #F2E9E4
+#3D5A80 #98C1D9 #E0FBFC #EE6C4D #293241
+#2B2D42 #8D99AE #EDF2F4 #EF233C #D90429
+#353535 #3C6E71 #FFFFFF #D9D9D9 #284B63
+#E7ECEF #274C77 #6096BA #A3CEF1 #8B8C89
+#CFDBD5 #E8EDDF #F5CB5C #242423 #333533
+#2F6690 #3A7CA5 #D9DCD6 #16425B #81C3D7
+```

package/.agents/skills/hyperframes-creative/palettes/dark-premium.md

@@ -0,0 +1,14 @@
+# Dark / Premium
+
+Tech, finance, luxury, cinematic content.
+
+```
+#000000 #14213D #FCA311 #E5E5E5 #FFFFFF
+#000814 #001D3D #003566 #FFC300 #FFD60A
+#0D1B2A #1B263B #415A77 #778DA9 #E0E1DD
+#0D1321 #1D2D44 #3E5C76 #748CAB #F0EBD8
+#011627 #FDFFFC #2EC4B6 #E71D36 #FF9F1C
+#0B090A #161A1D #660708 #A4161A #E5383B
+#001427 #708D81 #F4D58D #BF0603 #8D0801
+#001524 #15616D #FFECD1 #FF7D00 #78290F
+```

package/.agents/skills/hyperframes-creative/palettes/jewel-rich.md

@@ -0,0 +1,14 @@
+# Jewel / Rich
+
+Luxury, events, sophisticated, high-end content.
+
+```
+#5F0F40 #9A031E #FB8B24 #E36414 #0F4C5C
+#780000 #C1121F #FDF0D5 #003049 #669BBC
+#10002B #240046 #3C096C #5A189A #7B2CBF
+#355070 #6D597A #B56576 #E56B6F #EAAC8B
+#6F1D1B #BB9457 #432818 #99582A #FFE6A7
+#231942 #5E548E #9F86C0 #BE95C4 #E0B1CB
+#461220 #8C2F39 #B23A48 #FCB9B2 #FED0BB
+#780116 #F7B538 #DB7C26 #D8572A #C32F27
+```

package/.agents/skills/hyperframes-creative/palettes/monochrome.md

@@ -0,0 +1,14 @@
+# Monochrome
+
+Dramatic, typography-focused, serious content.
+
+```
+#F8F9FA #E9ECEF #DEE2E6 #CED4DA #ADB5BD #6C757D #495057 #343A40 #212529
+#0466C8 #0353A4 #023E7D #002855 #001233
+#012A4A #013A63 #01497C #2A6F97 #468FAF #89C2D9
+#582F0E #7F4F24 #936639 #A68A64 #C2C5AA
+#463F3A #8A817C #BCB8B1 #F4F3EE #E0AFA0
+#03071E #370617 #6A040F #9D0208 #DC2F02 #F48C06 #FFBA08
+#590D22 #800F2F #A4133C #FF4D6D #FF8FA3 #FFCCD5
+#220901 #621708 #941B0C #BC3908 #F6AA1C
+```

package/.agents/skills/hyperframes-creative/palettes/nature-earth.md

@@ -0,0 +1,14 @@
+# Nature / Earth
+
+Sustainability, outdoor, organic, wellness content.
+
+```
+#606C38 #283618 #FEFAE0 #DDA15E #BC6C25
+#DAD7CD #A3B18A #588157 #3A5A40 #344E41
+#386641 #6A994E #A7C957 #F2E8CF #BC4749
+#CAD2C5 #84A98C #52796F #354F52 #2F3E46
+#F0EAD2 #DDE5B6 #ADC178 #A98467 #6C584C
+#132A13 #31572C #4F772D #90A955 #ECF39E
+#6B9080 #A4C3B2 #CCE3DE #EAF4F4 #F6FFF8
+#233D4D #FE7F2D #FCCA46 #A1C181 #619B8A
+```

package/.agents/skills/hyperframes-creative/palettes/neon-electric.md

@@ -0,0 +1,14 @@
+# Neon / Electric
+
+Gaming, tech, nightlife, Gen Z content.
+
+```
+#F72585 #B5179E #7209B7 #560BAD #3A0CA3
+#70D6FF #FF70A6 #FF9770 #FFD670 #E9FF70
+#7400B8 #6930C3 #5E60CE #5390D9 #48BFE3
+#0B132B #1C2541 #3A506B #5BC0BE #6FFFE9
+#540D6E #EE4266 #FFD23F #3BCEAC #0EAD69
+#2D00F7 #6A00F4 #8900F2 #A100F2 #F20089
+#FF6D00 #FF7900 #FF8500 #FF9100 #240046
+#BBFBFF #8DD8FF #4E71FF #5409DA
+```

package/.agents/skills/hyperframes-creative/palettes/pastel-soft.md

@@ -0,0 +1,14 @@
+# Pastel / Soft
+
+Fashion, beauty, lifestyle, wellness content.
+
+```
+#CDB4DB #FFC8DD #FFAFCC #BDE0FE #A2D2FF
+#CCD5AE #E9EDC9 #FEFAE0 #FAEDCD #D4A373
+#FFD6FF #E7C6FF #C8B6FF #B8C0FF #BBD0FF
+#FFA69E #FAF3DD #B8F2E6 #AED9E0 #5E6472
+#EDAFB8 #F7E1D7 #DEDBD2 #B0C4B1 #4A5759
+#555B6E #89B0AE #BEE3DB #FAF9F9 #FFD6BA
+#006D77 #83C5BE #EDF6F9 #FFDDD2 #E29578
+#0081A7 #00AFB9 #FDFCDC #FED9B7 #F07167
+```

package/.agents/skills/hyperframes-creative/palettes/warm-editorial.md

@@ -0,0 +1,14 @@
+# Warm / Editorial
+
+Storytelling, documentaries, case studies, narrative content.
+
+```
+#264653 #2A9D8F #E9C46A #F4A261 #E76F51
+#335C67 #FFF3B0 #E09F3E #9E2A2B #540B0E
+#F4F1DE #E07A5F #3D405B #81B29A #F2CC8F
+#F6BD60 #F7EDE2 #F5CAC3 #84A59D #F28482
+#003049 #D62828 #F77F00 #FCBF49 #EAE2B7
+#588B8B #FFFFFF #FFD5C2 #F28F3B #C8553D
+#283D3B #197278 #EDDDD4 #C44536 #772E25
+#0D3B66 #FAF0CA #F4D35E #EE964B #F95738
+```

package/.agents/skills/hyperframes-creative/references/audio-reactive.md

@@ -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 this skill's `scripts/`)
+- No `Math.random()` or `Date.now()`
+- Audio reactivity runs on the same GSAP timeline as everything else

package/.agents/skills/hyperframes-creative/references/beat-direction.md

@@ -0,0 +1,164 @@
+# Beat Direction
+
+How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video.
+
+## Contents
+
+- Per-beat direction
+- Concept
+- Mood direction
+- Animation choreography
+- Transition
+- Depth layers
+- SFX cues
+- Rhythm planning
+- Velocity-matched transitions
+
+---
+
+## Per-Beat Direction
+
+Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
+
+**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
+**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
+
+The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
+
+Each beat should have:
+
+### Concept
+
+The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
+
+### Mood direction
+
+Cultural and design references, not hex codes:
+
+- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
+- "Warm workspace. Nice notebook energy, not technical blueprint."
+- "Cinematic title sequence. The kind of opening where you lean forward."
+
+### Animation choreography
+
+Specific motion verbs per element — not "it animates in" but HOW. Verbs come from the beat's concept and content, not from an energy bucket. A wellness brand's "slow" beat might still have something that DROPS if the content is about letting go. A stats beat might FLOAT if the brand's identity is weightless.
+
+The vocabulary of motion verbs (organized by physical character, not by energy level):
+
+**Impact / weight:** SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS, DROPS (with force)
+**Directional / deliberate:** SLIDES, PUSHES, PULLS, WIPES, CUTS
+**Reveals / builds:** DRAWS, FILLS, GROWS, EXPANDS, ASSEMBLES, COUNTS UP
+**Organic / ambient:** FLOATS, DRIFTS, BREATHES, PULSES, ORBITS, MORPHS
+**Mechanical / precise:** TYPES ON, CLICKS, LOCKS IN, SNAPS, STEPS
+
+Every element gets a verb. If you can't name the verb, the element is not yet designed. The verb should follow from the beat's concept — not from a lookup of what "high energy" or "low energy" beats use.
+
+For text elements specifically, you can name a deterministic, named effect by ID (e.g. `typewriter`, `kinetic-center-build`, `soft-blur-in`) instead of inventing timing from scratch — the 24-effect vocabulary and how to load it live in `skills/hyperframes-animation/adapters/animate-text.md`.
+
+### Transition
+
+How this beat hands off to the next. Specify the type and parameters.
+
+**When to pick which:**
+
+| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
+| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
+| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
+
+Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, a CSS crossfade is fine. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) — too many flatten their impact.
+
+**Mixing shader and CSS crossfade transitions in one composition is supported.** Omit `shader` on any transition entry to get a smooth opacity crossfade — HyperShader manages all scene visibility regardless. Let HyperShader create the timeline (don't pass a pre-built `timeline:` option) and add all composition tweens to the returned `tl` after `init()`. Config snippet in `skills/hyperframes-animation/transitions/overview.md` → "CSS vs Shader".
+
+**CSS transitions** — 30+ patterns across 13 categories. Full code in `skills/hyperframes-animation/transitions/` (route via `catalog.md`). Pick based on the energy and feel:
+
+| Category           | Patterns                                                                 | Motion character                                                           |
+| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| **Push / slide**   | Push slide, vertical push, elastic push, squeeze                         | Content moves through the frame as if on a continuous surface              |
+| **Scale / zoom**   | Zoom through, zoom out                                                   | Perspective shifts — moving toward or away from content                    |
+| **Radial / clip**  | Circle iris, diamond iris, diagonal split                                | Geometric reveal — content emerges or is covered by a shape                |
+| **3D**             | 3D card flip                                                             | Physical — content flips like a tangible object                            |
+| **Dissolve**       | Crossfade, blur crossfade, focus pull, color dip                         | Overlap and blend — both scenes exist simultaneously during the transition |
+| **Cover / blinds** | Staggered color blocks, horizontal blinds (6/12 strips), vertical blinds | Structural — content is sliced, layered, or covered                        |
+| **Light**          | Light leak overlays, overexposure burn, film burn                        | Organic film — light bleeds across the frame                               |
+| **Distortion**     | Glitch (CSS RGB jitter), chromatic aberration, ripple, VHS tape          | Instability — the image itself appears to malfunction                      |
+| **Blur**           | Blur through, directional blur                                           | Soft defocus — content blurs in or out                                     |
+| **Mechanical**     | Shutter (two-half), clock wipe (9-point wedge)                           | Precision — transitions with visible mechanical logic                      |
+| **Grid**           | Grid dissolve (12/120 cells)                                             | Fragmentation — the frame breaks into pieces                               |
+| **Destruction**    | Page burn (SVG clip-path + canvas rim)                                   | Dramatic decay — the previous scene is destroyed                           |
+| **Other**          | Gravity drop, morph circle                                               | Physical or shape-based motion that doesn't fit other categories           |
+
+Common quick-picks:
+
+- **Velocity-matched upward**: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
+- **Whip pan**: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
+- **Blur through**: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
+- **Zoom through**: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
+- **Hard cut / smash cut**: instant, for rapid-fire sequences
+
+Timing presets: snappy (0.2s), smooth (0.4s), gentle (0.6s), dramatic (0.5s), instant (0.15s), luxe (0.7s).
+
+**Shader transitions** — 14 built-in WebGL GPU effects. Install with `npx hyperframes add <name>` (block name ≠ shader name — see `skills/hyperframes-registry/references/discovery.md`); full API in `packages/shader-transitions/README.md`.
+
+| Shader                  | Visual description                                                                             | Duration range |
+| ----------------------- | ---------------------------------------------------------------------------------------------- | -------------- |
+| **domain-warp**         | Organic FBM dissolve — both scenes warp toward each other with an accent flash at the midpoint | 0.5–0.8s       |
+| **ridged-burn**         | Multifractal mask reveals the incoming scene through a burn ramp with sparks at the edge       | 0.5–0.8s       |
+| **whip-pan**            | 10-sample horizontal motion blur + lateral crossfade — reads like a camera pan between shots   | 0.3–0.5s       |
+| **sdf-iris**            | Circle SDF expands from center, with accent-tinted glow rings at the expanding edge            | 0.5–0.7s       |
+| **ripple-waves**        | Radial standing-wave UV displacement — content ripples outward as scenes cross                 | 0.6–1.0s       |
+| **gravitational-lens**  | Pinch pull toward center + R/B chromatic separation — content bends inward then releases       | 0.6–1.0s       |
+| **cinematic-zoom**      | 12 RGB-offset radial zoom blur samples — motion streak radiating from center                   | 0.4–0.6s       |
+| **chromatic-split**     | R/B radial channel shift outward, G fixed — channels separate then rejoin                      | 0.3–0.5s       |
+| **swirl-vortex**        | CCW swirl with FBM noise — content spirals away and the new scene spirals in                   | 0.5–0.8s       |
+| **thermal-distortion**  | Vertical sine + FBM horizontal displacement — heat-haze shimmer across the frame               | 0.5–0.8s       |
+| **flash-through-white** | Fade through white midpoint — almost invisible at 0.01s, noticeable at 0.3s                    | 0.01s–0.3s     |
+| **cross-warp-morph**    | FBM vector field displaces both scenes; a third FBM biases the wipe direction                  | 0.5–0.8s       |
+| **light-leak**          | Fixed off-frame light source with exponential falloff, warmth, and a ridge flare               | 0.5–0.8s       |
+| **glitch**              | Line displacement + RGB lateral split + scan modulation + posterization + flicker              | 0.3–0.5s       |
+
+**You are not limited to what's listed here.** These are the built-in options, but you can and should:
+
+- **Write custom GLSL shaders** from scratch for unique transition effects
+- **Search online** for shader code (ShaderToy, GLSL Sandbox, GitHub) and adapt it
+- **Build custom CSS transitions** that aren't in any category — combine clip-path, transforms, filters in new ways
+- **Ask the user** to provide or find specific effects if you need something specialized
+
+If the storyboard calls for an effect that doesn't exist yet — build it. The framework renders anything a browser can run.
+
+### Depth layers
+
+What's in foreground, midground, and background. Every beat should have at least 2 layers:
+
+- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
+
+### SFX cues
+
+What sounds at what moment:
+
+- "On the capture pulse — a soft, warm analog shutter click."
+- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
+
+---
+
+## Rhythm Planning
+
+Before writing HTML, declare your scene rhythm: which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern — fast-fast-SLOW-fast-SHADER-hold — before implementing.
+
+**Derive the rhythm from the storyboard and the brand, not from a lookup.** A 15-second social ad for an architectural firm and a 15-second social ad for a gaming brand have different rhythms — both are 15 seconds, but one is slow-reveal-hold-CTA and the other is rapid-fire-SLAM-hook. Video type sets constraints (duration, approximate beat count); the brand and content determine whether those beats are slow or fast, sparse or dense, dramatic or controlled.
+
+Questions that drive rhythm decisions:
+
+- What emotional journey should the viewer take? Where is the peak moment?
+- Where does the narration land its heaviest emphasis? That's usually where energy should peak.
+- What does the brand's own visual pacing suggest — unhurried or urgent?
+- How many beats can the duration actually support without feeling rushed or padded?
+
+A social ad that tries to hook in 2s, showcase 3 features, and end with a CTA in 15s will feel like noise. Sometimes "hook-hold-CTA" with one strong feature is the right rhythm for 15 seconds. Name the rhythm you've planned before implementing.
+
+---
+
+## Velocity-Matched Transitions
+
+Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.

package/.agents/skills/hyperframes-creative/references/composition-patterns.md

@@ -0,0 +1,199 @@
+# Composition Patterns
+
+## Contents
+
+- Picture-in-picture
+- Text behind subject
+- Title card with fade
+- Slide show with section headers
+- Top-level composition example
+
+## Picture-in-Picture (Video in a Frame)
+
+Animate a wrapper div for position/size. The video fills the wrapper. The wrapper has NO data attributes.
+
+```html
+<div
+  id="pip-frame"
+  style="position:absolute;top:0;left:0;width:1920px;height:1080px;z-index:50;overflow:hidden;"
+>
+  <video
+    id="el-video"
+    data-start="0"
+    data-duration="60"
+    data-track-index="0"
+    src="talking-head.mp4"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+```js
+tl.to(
+  "#pip-frame",
+  { top: 700, left: 1360, width: 500, height: 280, borderRadius: 16, duration: 1 },
+  10,
+);
+tl.to("#pip-frame", { left: 40, duration: 0.6 }, 30);
+```
+
+## Text Behind Subject (transparent webm overlay)
+
+Put a headline _behind_ a presenter so their silhouette occludes the text. Requires a transparent cutout produced by `npx hyperframes remove-background presenter.mp4 -o presenter.webm`.
+
+Three layers, plus one critical rule:
+
+```html
+<!-- z=1 base — full opaque mp4 (lobby + presenter), always visible -->
+<video
+  id="cf-base"
+  data-start="0"
+  data-duration="6"
+  data-media-start="0"
+  data-track-index="0"
+  src="presenter.mp4"
+  muted
+  playsinline
+></video>
+
+<!-- z=2 headline — visible the whole time -->
+<h1
+  id="cf-headline"
+  style="position:absolute;top:50%;left:50%;
+     transform:translate(-50%,-50%); z-index:2; font-size:220px; font-weight:900;
+     color:#fff; text-shadow:0 6px 32px rgba(0,0,0,.55); clip-path:inset(0 0 100% 0);"
+>
+  MAKE IT IN HYPERFRAMES
+</h1>
+
+<!-- z=3 cutout — same source, alpha around presenter, hidden until the cut -->
+<!-- WRAPPER has the opacity, NOT the video itself (see rule below). -->
+<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
+  <video
+    id="cf-cutout"
+    data-start="0"
+    data-duration="6"
+    data-media-start="0"
+    data-track-index="1"
+    src="presenter.webm"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+```js
+const tl = gsap.timeline({ paused: true });
+const CUT = 3.3;
+
+// Reveal headline early
+tl.to("#cf-headline", { clipPath: "inset(0 0 0% 0)", duration: 0.6, ease: "expo.out" }, 0.25);
+
+// At the cut, flip the cutout wrapper visible — the presenter's silhouette
+// punches through the headline.
+tl.set(".cutout-wrap", { opacity: 1 }, CUT);
+
+// Sentinel: extend timeline to the composition's full duration so the
+// renderer doesn't bail past the last meaningful tween.
+tl.set({}, {}, 6);
+
+window.__timelines["cover-flip"] = tl;
+```
+
+**Why a wrapper div, not opacity on the video itself?**
+
+The framework forces `opacity: 1` on any element with `data-start`/`data-duration` while it's "active" — that's how it manages clip lifecycles. A CSS `opacity: 0` on the video element is silently overwritten. Wrap the video in a div with no `data-*` attributes; the wrapper is owned by your CSS/GSAP.
+
+**Why both videos at `data-start="0"`?**
+
+So both decode in sync from t=0. Late-mounting the cutout (`data-start=3.3`) makes Chrome do a seek + decoder warm-up at mount, which can land a frame off the base mp4 — visible as a one-frame jitter at the cut.
+
+**Color match:** `remove-background` defaults to `--quality balanced` (crf 18) which keeps the cutout's RGB nearly identical to the source mp4 — minimal edge halo or color shift when overlaid. Use `--quality best` (crf 12) for hero shots; only drop to `--quality fast` (crf 30) when the cutout sits over a _different_ background and the size matters.
+
+## Title Card with Fade
+
+```html
+<div
+  id="title-card"
+  data-start="0"
+  data-duration="5"
+  data-track-index="5"
+  style="display:flex;align-items:center;justify-content:center;background:#111;z-index:60;"
+>
+  <h1 style="font-size:64px;color:#fff;opacity:0;">My Video Title</h1>
+</div>
+```
+
+```js
+tl.to("#title-card h1", { opacity: 1, duration: 0.6 }, 0.3);
+tl.to("#title-card", { opacity: 0, duration: 0.5 }, 4);
+```
+
+## Slide Show with Section Headers
+
+Use separate elements on the same track, each with its own time range. Slides auto-mount/unmount based on `data-start`/`data-duration`.
+
+```html
+<div class="slide" data-start="0" data-duration="30" data-track-index="3">...</div>
+<div class="slide" data-start="30" data-duration="25" data-track-index="3">...</div>
+<div class="slide" data-start="55" data-duration="20" data-track-index="3">...</div>
+```
+
+## Top-Level Composition Example
+
+```html
+<div
+  id="comp-1"
+  data-composition-id="my-video"
+  data-start="0"
+  data-duration="60"
+  data-width="1920"
+  data-height="1080"
+>
+  <!-- Primitive clips -->
+  <video
+    id="el-1"
+    data-start="0"
+    data-duration="10"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <video
+    id="el-2"
+    data-start="el-1"
+    data-duration="8"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <img id="el-3" data-start="5" data-duration="4" data-track-index="1" src="..." />
+  <audio id="el-4" data-start="0" data-duration="30" data-track-index="2" src="..." />
+
+  <!-- Sub-compositions loaded from files -->
+  <div
+    id="el-5"
+    data-composition-id="intro-anim"
+    data-composition-src="compositions/intro-anim.html"
+    data-start="0"
+    data-track-index="3"
+  ></div>
+
+  <div
+    id="el-6"
+    data-composition-id="captions"
+    data-composition-src="compositions/caption-overlay.html"
+    data-start="0"
+    data-track-index="4"
+  ></div>
+
+  <script>
+    // Just register the timeline — framework auto-nests sub-compositions
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["my-video"] = tl;
+  </script>
+</div>
+```

package/.agents/skills/hyperframes-creative/references/data-in-motion.md

@@ -0,0 +1,19 @@
+# Data in Motion
+
+Light guidance for data and stats in video compositions. `house-style.md` handles aesthetics; this just addresses data-specific pitfalls.
+
+## Visual Continuity
+
+When successive stats belong to the same concept (Q1 → Q2 → Q3 → Q4, or three metrics for the same product), keep them in the same visual space with the same aesthetic. Only the VALUE changes. An aesthetic change should signal a new concept, not just a new number.
+
+## Numbers Need Visual Weight
+
+A number on its own floats in empty space. Pair every metric with a visual element that gives it presence — a proportional fill bar, a background color shift, a shape that represents the value, a progress ring. The visual doesn't need to be a chart — it just needs to fill the frame and make the data feel tangible rather than just text on a background.
+
+## Avoid Web Patterns
+
+- **No pie charts** — hard to compare, looks like PowerPoint
+- **No multi-axis charts** — viewer can't study intersections in a 3-second window
+- **No 6-panel dashboards** — 2-3 related metrics side-by-side is fine, 6+ is a web pattern
+- **No gridlines, tick marks, or legends** — visual noise that adds nothing in motion
+- **No chart library output** — build with GSAP + SVG/CSS, not D3 or Chart.js

package/.agents/skills/hyperframes-creative/references/design-adherence.md

@@ -0,0 +1,19 @@
+# Design Adherence
+
+Post-authoring verification that the composition follows the design spec. Run it after building, before serving the preview.
+
+If a design spec (`frame.md` / `design.md`) exists, read the HTML and check:
+
+1. **Colors** — every hex value in the composition appears in the spec's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors.
+2. **Typography** — font families and weights match the spec's type spec. No substitutions.
+3. **Corners** — border-radius values match the declared corner style, if specified.
+4. **Spacing** — padding and gap values fall within the declared density range, if specified.
+5. **Depth** — shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows).
+6. **Avoidance rules** — if the spec has a section listing things to avoid (commonly "What NOT to Do", "Don'ts", "Anti-patterns", or "Do's and Don'ts"), verify none are present.
+
+Report violations as a checklist. Fix each one before serving.
+
+If no design spec exists (house-style-only path), verify:
+
+1. **Palette consistency** — the same bg, fg, and accent colors are used across all scenes. No per-scene color invention.
+2. **No lazy defaults** — check the composition against `house-style.md`'s "Lazy Defaults to Question" list. If any appear, they must be a deliberate choice for the content, not a default.